Rename fail! to panic!
https://github.com/rust-lang/rfcs/pull/221 The current terminology of "task failure" often causes problems when writing or speaking about code. You often want to talk about the possibility of an operation that returns a Result "failing", but cannot because of the ambiguity with task failure. Instead, you have to speak of "the failing case" or "when the operation does not succeed" or other circumlocutions. Likewise, we use a "Failure" header in rustdoc to describe when operations may fail the task, but it would often be helpful to separate out a section describing the "Err-producing" case. We have been steadily moving away from task failure and toward Result as an error-handling mechanism, so we should optimize our terminology accordingly: Result-producing functions should be easy to describe. To update your code, rename any call to `fail!` to `panic!` instead. Assuming you have not created your own macro named `panic!`, this will work on UNIX based systems: grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g' You can of course also do this by hand. [breaking-change]
This commit is contained in:
Steve Klabnik
parent
3bc545373d
commit
7828c3dd28
505 changed files with 1623 additions and 1618 deletions
|
|
@ -46,13 +46,13 @@
|
|||
//! ## Failure Propagation
|
||||
//!
|
||||
//! In addition to being a core primitive for communicating in rust, channels
|
||||
//! are the points at which failure is propagated among tasks. Whenever the one
|
||||
//! are the points at which panics are propagated among tasks. Whenever the one
|
||||
//! half of channel is closed, the other half will have its next operation
|
||||
//! `fail!`. The purpose of this is to allow propagation of failure among tasks
|
||||
//! `panic!`. The purpose of this is to allow propagation of panics among tasks
|
||||
//! that are linked to one another via channels.
|
||||
//!
|
||||
//! There are methods on both of senders and receivers to perform their
|
||||
//! respective operations without failing, however.
|
||||
//! respective operations without panicking, however.
|
||||
//!
|
||||
//! ## Runtime Requirements
|
||||
//!
|
||||
|
|
@ -102,10 +102,10 @@
|
|||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! Propagating failure:
|
||||
//! Propagating panics:
|
||||
//!
|
||||
//! ```should_fail
|
||||
//! // The call to recv() will fail!() because the channel has already hung
|
||||
//! // The call to recv() will panic!() because the channel has already hung
|
||||
//! // up (or been deallocated)
|
||||
//! let (tx, rx) = channel::<int>();
|
||||
//! drop(tx);
|
||||
|
|
@ -506,7 +506,7 @@ pub fn channel<T: Send>() -> (Sender<T>, Receiver<T>) {
|
|||
/// becomes "rendezvous channel" where each send will not return until a recv
|
||||
/// is paired with it.
|
||||
///
|
||||
/// As with asynchronous channels, all senders will fail in `send` if the
|
||||
/// As with asynchronous channels, all senders will panic in `send` if the
|
||||
/// `Receiver` has been destroyed.
|
||||
///
|
||||
/// # Example
|
||||
|
|
@ -550,25 +550,25 @@ impl<T: Send> Sender<T> {
|
|||
///
|
||||
/// Rust channels are infinitely buffered so this method will never block.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// This function will fail if the other end of the channel has hung up.
|
||||
/// This function will panic if the other end of the channel has hung up.
|
||||
/// This means that if the corresponding receiver has fallen out of scope,
|
||||
/// this function will trigger a fail message saying that a message is
|
||||
/// this function will trigger a panic message saying that a message is
|
||||
/// being sent on a closed channel.
|
||||
///
|
||||
/// Note that if this function does *not* fail, it does not mean that the
|
||||
/// Note that if this function does *not* panic, it does not mean that the
|
||||
/// data will be successfully received. All sends are placed into a queue,
|
||||
/// so it is possible for a send to succeed (the other end is alive), but
|
||||
/// then the other end could immediately disconnect.
|
||||
///
|
||||
/// The purpose of this functionality is to propagate failure among tasks.
|
||||
/// If failure is not desired, then consider using the `send_opt` method
|
||||
/// The purpose of this functionality is to propagate panicks among tasks.
|
||||
/// If a panic is not desired, then consider using the `send_opt` method
|
||||
#[experimental = "this function is being considered candidate for removal \
|
||||
to adhere to the general guidelines of rust"]
|
||||
pub fn send(&self, t: T) {
|
||||
if self.send_opt(t).is_err() {
|
||||
fail!("sending on a closed channel");
|
||||
panic!("sending on a closed channel");
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -585,9 +585,9 @@ impl<T: Send> Sender<T> {
|
|||
///
|
||||
/// Like `send`, this method will never block.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// This method will never fail, it will return the message back to the
|
||||
/// This method will never panic, it will return the message back to the
|
||||
/// caller if the other end is disconnected
|
||||
///
|
||||
/// # Example
|
||||
|
|
@ -634,7 +634,7 @@ impl<T: Send> Sender<T> {
|
|||
}
|
||||
oneshot::UpDisconnected => (a, Err(t)),
|
||||
oneshot::UpWoke(task) => {
|
||||
// This send cannot fail because the task is
|
||||
// This send cannot panic because the task is
|
||||
// asleep (we're looking at it), so the receiver
|
||||
// can't go away.
|
||||
(*a.get()).send(t).ok().unwrap();
|
||||
|
|
@ -731,20 +731,20 @@ impl<T: Send> SyncSender<T> {
|
|||
/// time. If the buffer size is 0, however, it can be guaranteed that the
|
||||
/// receiver has indeed received the data if this function returns success.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// Similarly to `Sender::send`, this function will fail if the
|
||||
/// Similarly to `Sender::send`, this function will panic if the
|
||||
/// corresponding `Receiver` for this channel has disconnected. This
|
||||
/// behavior is used to propagate failure among tasks.
|
||||
/// behavior is used to propagate panics among tasks.
|
||||
///
|
||||
/// If failure is not desired, you can achieve the same semantics with the
|
||||
/// `SyncSender::send_opt` method which will not fail if the receiver
|
||||
/// If a panic is not desired, you can achieve the same semantics with the
|
||||
/// `SyncSender::send_opt` method which will not panic if the receiver
|
||||
/// disconnects.
|
||||
#[experimental = "this function is being considered candidate for removal \
|
||||
to adhere to the general guidelines of rust"]
|
||||
pub fn send(&self, t: T) {
|
||||
if self.send_opt(t).is_err() {
|
||||
fail!("sending on a closed channel");
|
||||
panic!("sending on a closed channel");
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -756,9 +756,9 @@ impl<T: Send> SyncSender<T> {
|
|||
/// is returned back to the callee. This function is similar to `try_send`,
|
||||
/// except that it will block if the channel is currently full.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// This function cannot fail.
|
||||
/// This function cannot panic.
|
||||
#[unstable = "this function may be renamed to send() in the future"]
|
||||
pub fn send_opt(&self, t: T) -> Result<(), T> {
|
||||
unsafe { (*self.inner.get()).send(t) }
|
||||
|
|
@ -774,9 +774,9 @@ impl<T: Send> SyncSender<T> {
|
|||
/// See `SyncSender::send` for notes about guarantees of whether the
|
||||
/// receiver has received the data or not if this function is successful.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// This function cannot fail
|
||||
/// This function cannot panic
|
||||
#[unstable = "the return type of this function is candidate for \
|
||||
modification"]
|
||||
pub fn try_send(&self, t: T) -> Result<(), TrySendError<T>> {
|
||||
|
|
@ -814,13 +814,13 @@ impl<T: Send> Receiver<T> {
|
|||
/// on the channel from its paired `Sender` structure. This receiver will
|
||||
/// be woken up when data is ready, and the data will be returned.
|
||||
///
|
||||
/// # Failure
|
||||
/// # Panics
|
||||
///
|
||||
/// Similar to channels, this method will trigger a task failure if the
|
||||
/// Similar to channels, this method will trigger a task panic if the
|
||||
/// other end of the channel has hung up (been deallocated). The purpose of
|
||||
/// this is to propagate failure among tasks.
|
||||
/// this is to propagate panicks among tasks.
|
||||
///
|
||||
/// If failure is not desired, then there are two options:
|
||||
/// If a panic is not desired, then there are two options:
|
||||
///
|
||||
/// * If blocking is still desired, the `recv_opt` method will return `None`
|
||||
/// when the other end hangs up
|
||||
|
|
@ -832,7 +832,7 @@ impl<T: Send> Receiver<T> {
|
|||
pub fn recv(&self) -> T {
|
||||
match self.recv_opt() {
|
||||
Ok(t) => t,
|
||||
Err(()) => fail!("receiving on a closed channel"),
|
||||
Err(()) => panic!("receiving on a closed channel"),
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -845,7 +845,9 @@ impl<T: Send> Receiver<T> {
|
|||
/// This is useful for a flavor of "optimistic check" before deciding to
|
||||
/// block on a receiver.
|
||||
///
|
||||
/// This function cannot fail.
|
||||
/// # Panics
|
||||
///
|
||||
/// This function cannot panic.
|
||||
#[unstable = "the return type of this function may be altered"]
|
||||
pub fn try_recv(&self) -> Result<T, TryRecvError> {
|
||||
// If a thread is spinning in try_recv, we should take the opportunity
|
||||
|
|
@ -899,15 +901,15 @@ impl<T: Send> Receiver<T> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Attempt to wait for a value on this receiver, but does not fail if the
|
||||
/// Attempt to wait for a value on this receiver, but does not panic if the
|
||||
/// corresponding channel has hung up.
|
||||
///
|
||||
/// This implementation of iterators for ports will always block if there is
|
||||
/// not data available on the receiver, but it will not fail in the case
|
||||
/// not data available on the receiver, but it will not panic in the case
|
||||
/// that the channel has been deallocated.
|
||||
///
|
||||
/// In other words, this function has the same semantics as the `recv`
|
||||
/// method except for the failure aspect.
|
||||
/// method except for the panic aspect.
|
||||
///
|
||||
/// If the channel has hung up, then `Err` is returned. Otherwise `Ok` of
|
||||
/// the value found on the receiver is returned.
|
||||
|
|
@ -947,7 +949,7 @@ impl<T: Send> Receiver<T> {
|
|||
}
|
||||
|
||||
/// Returns an iterator which will block waiting for messages, but never
|
||||
/// `fail!`. It will return `None` when the channel has hung up.
|
||||
/// `panic!`. It will return `None` when the channel has hung up.
|
||||
#[unstable]
|
||||
pub fn iter<'a>(&'a self) -> Messages<'a, T> {
|
||||
Messages { rx: self }
|
||||
|
|
@ -1191,7 +1193,7 @@ mod test {
|
|||
assert_eq!(rx.recv(), 1);
|
||||
}
|
||||
match rx.try_recv() {
|
||||
Ok(..) => fail!(),
|
||||
Ok(..) => panic!(),
|
||||
_ => {}
|
||||
}
|
||||
dtx.send(());
|
||||
|
|
@ -1287,7 +1289,7 @@ mod test {
|
|||
} #[should_fail])
|
||||
|
||||
test!(fn oneshot_single_thread_recv_chan_close() {
|
||||
// Receiving on a closed chan will fail
|
||||
// Receiving on a closed chan will panic
|
||||
let res = task::try(proc() {
|
||||
let (tx, rx) = channel::<int>();
|
||||
drop(tx);
|
||||
|
|
@ -1711,7 +1713,7 @@ mod sync_tests {
|
|||
assert_eq!(rx.recv(), 1);
|
||||
}
|
||||
match rx.try_recv() {
|
||||
Ok(..) => fail!(),
|
||||
Ok(..) => panic!(),
|
||||
_ => {}
|
||||
}
|
||||
dtx.send(());
|
||||
|
|
@ -1747,7 +1749,7 @@ mod sync_tests {
|
|||
} #[should_fail])
|
||||
|
||||
test!(fn oneshot_single_thread_recv_chan_close() {
|
||||
// Receiving on a closed chan will fail
|
||||
// Receiving on a closed chan will panic
|
||||
let res = task::try(proc() {
|
||||
let (tx, rx) = sync_channel::<int>(0);
|
||||
drop(tx);
|
||||
|
|
|
|||
|
|
@ -94,7 +94,7 @@ impl<T: Send> Packet<T> {
|
|||
// Sanity check
|
||||
match self.upgrade {
|
||||
NothingSent => {}
|
||||
_ => fail!("sending on a oneshot that's already sent on "),
|
||||
_ => panic!("sending on a oneshot that's already sent on "),
|
||||
}
|
||||
assert!(self.data.is_none());
|
||||
self.data = Some(t);
|
||||
|
|
@ -203,7 +203,7 @@ impl<T: Send> Packet<T> {
|
|||
let prev = match self.upgrade {
|
||||
NothingSent => NothingSent,
|
||||
SendUsed => SendUsed,
|
||||
_ => fail!("upgrading again"),
|
||||
_ => panic!("upgrading again"),
|
||||
};
|
||||
self.upgrade = GoUp(up);
|
||||
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@ pub trait Packet {
|
|||
|
||||
impl Select {
|
||||
/// Creates a new selection structure. This set is initially empty and
|
||||
/// `wait` will fail!() if called.
|
||||
/// `wait` will panic!() if called.
|
||||
///
|
||||
/// Usage of this struct directly can sometimes be burdensome, and usage is
|
||||
/// rather much easier through the `select!` macro.
|
||||
|
|
@ -353,17 +353,17 @@ mod test {
|
|||
tx1.send(1);
|
||||
select! (
|
||||
foo = rx1.recv() => { assert_eq!(foo, 1); },
|
||||
_bar = rx2.recv() => { fail!() }
|
||||
_bar = rx2.recv() => { panic!() }
|
||||
)
|
||||
tx2.send(2);
|
||||
select! (
|
||||
_foo = rx1.recv() => { fail!() },
|
||||
_foo = rx1.recv() => { panic!() },
|
||||
bar = rx2.recv() => { assert_eq!(bar, 2) }
|
||||
)
|
||||
drop(tx1);
|
||||
select! (
|
||||
foo = rx1.recv_opt() => { assert_eq!(foo, Err(())); },
|
||||
_bar = rx2.recv() => { fail!() }
|
||||
_bar = rx2.recv() => { panic!() }
|
||||
)
|
||||
drop(tx2);
|
||||
select! (
|
||||
|
|
@ -379,10 +379,10 @@ mod test {
|
|||
let (tx5, rx5) = channel::<int>();
|
||||
tx5.send(4);
|
||||
select! (
|
||||
_foo = rx1.recv() => { fail!("1") },
|
||||
_foo = rx2.recv() => { fail!("2") },
|
||||
_foo = rx3.recv() => { fail!("3") },
|
||||
_foo = rx4.recv() => { fail!("4") },
|
||||
_foo = rx1.recv() => { panic!("1") },
|
||||
_foo = rx2.recv() => { panic!("2") },
|
||||
_foo = rx3.recv() => { panic!("3") },
|
||||
_foo = rx4.recv() => { panic!("4") },
|
||||
foo = rx5.recv() => { assert_eq!(foo, 4); }
|
||||
)
|
||||
})
|
||||
|
|
@ -393,7 +393,7 @@ mod test {
|
|||
drop(tx2);
|
||||
|
||||
select! (
|
||||
_a1 = rx1.recv_opt() => { fail!() },
|
||||
_a1 = rx1.recv_opt() => { panic!() },
|
||||
a2 = rx2.recv_opt() => { assert_eq!(a2, Err(())); }
|
||||
)
|
||||
})
|
||||
|
|
@ -412,12 +412,12 @@ mod test {
|
|||
|
||||
select! (
|
||||
a = rx1.recv() => { assert_eq!(a, 1); },
|
||||
_b = rx2.recv() => { fail!() }
|
||||
_b = rx2.recv() => { panic!() }
|
||||
)
|
||||
tx3.send(1);
|
||||
select! (
|
||||
a = rx1.recv_opt() => { assert_eq!(a, Err(())); },
|
||||
_b = rx2.recv() => { fail!() }
|
||||
_b = rx2.recv() => { panic!() }
|
||||
)
|
||||
})
|
||||
|
||||
|
|
@ -488,7 +488,7 @@ mod test {
|
|||
tx3.send(());
|
||||
select!(
|
||||
_i1 = rx1.recv() => {},
|
||||
_i2 = rx2.recv() => fail!()
|
||||
_i2 = rx2.recv() => panic!()
|
||||
)
|
||||
tx3.send(());
|
||||
})
|
||||
|
|
@ -509,7 +509,7 @@ mod test {
|
|||
tx3.send(());
|
||||
select!(
|
||||
_i1 = rx1.recv() => {},
|
||||
_i2 = rx2.recv() => fail!()
|
||||
_i2 = rx2.recv() => panic!()
|
||||
)
|
||||
tx3.send(());
|
||||
})
|
||||
|
|
|
|||
|
|
@ -299,7 +299,7 @@ impl<T: Send> Packet<T> {
|
|||
Thread::yield_now();
|
||||
match self.queue.pop() {
|
||||
mpsc::Data(t) => { data = t; break }
|
||||
mpsc::Empty => fail!("inconsistent => empty"),
|
||||
mpsc::Empty => panic!("inconsistent => empty"),
|
||||
mpsc::Inconsistent => {}
|
||||
}
|
||||
}
|
||||
|
|
@ -358,7 +358,7 @@ impl<T: Send> Packet<T> {
|
|||
match self.channels.fetch_sub(1, atomic::SeqCst) {
|
||||
1 => {}
|
||||
n if n > 1 => return,
|
||||
n => fail!("bad number of channels left {}", n),
|
||||
n => panic!("bad number of channels left {}", n),
|
||||
}
|
||||
|
||||
match self.cnt.swap(DISCONNECTED, atomic::SeqCst) {
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
/// which means that every successful send is paired with a successful recv.
|
||||
///
|
||||
/// This flavor of channels defines a new `send_opt` method for channels which
|
||||
/// is the method by which a message is sent but the task does not fail if it
|
||||
/// is the method by which a message is sent but the task does not panic if it
|
||||
/// cannot be delivered.
|
||||
///
|
||||
/// Another major difference is that send() will *always* return back the data
|
||||
|
|
@ -193,7 +193,7 @@ impl<T: Send> Packet<T> {
|
|||
// success, someone's about to receive our buffered data.
|
||||
BlockedReceiver(task) => { wakeup(task, guard); Ok(()) }
|
||||
|
||||
BlockedSender(..) => fail!("lolwut"),
|
||||
BlockedSender(..) => panic!("lolwut"),
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue