pub struct Receiver<T> { /* private fields */ }
Expand description
Receiving end of a oneshot channel.
Created and returned from the channel
function.
Can be used to receive a message from the corresponding Sender
. How the message
can be received depends on what features are enabled.
This type implement IntoFuture
when the async
feature is enabled.
This allows awaiting it directly in an async context.
Implementations§
Source§impl<T> Receiver<T>
impl<T> Receiver<T>
Sourcepub fn try_recv(&self) -> Result<T, TryRecvError>
pub fn try_recv(&self) -> Result<T, TryRecvError>
Checks if there is a message in the channel without blocking. Returns:
Ok(message)
if there was a message in the channel.Err(Empty)
if theSender
is alive, but has not yet sent a message.Err(Disconnected)
if theSender
was dropped before sending anything or if the message has already been extracted by a previous receive call.
If a message is returned, the channel is disconnected and any subsequent receive operation using this receiver will return an error.
This method is completely lock-free and wait-free. The only thing it does is an atomic integer load of the channel state. And if there is a message in the channel it additionally performs one atomic integer store and copies the message from the heap to the stack for returning it.
Sourcepub fn recv(self) -> Result<T, RecvError>
Available on crate feature std
only.
pub fn recv(self) -> Result<T, RecvError>
std
only.Attempts to wait for a message from the Sender
, returning an error if the channel is
disconnected.
This method will always block the current thread if there is no data available and it is
still possible for the message to be sent. Once the message is sent to the corresponding
Sender
, then this receiver will wake up and return that message.
If the corresponding Sender
has disconnected (been dropped), or it disconnects while
this call is blocking, this call will wake up and return Err
to indicate that the message
can never be received on this channel.
If a sent message has already been extracted from this channel this method will return an error.
§Panics
Panics if called after this receiver has been polled asynchronously.
Sourcepub fn recv_ref(&self) -> Result<T, RecvError>
Available on crate feature std
only.
pub fn recv_ref(&self) -> Result<T, RecvError>
std
only.Attempts to wait for a message from the Sender
, returning an error if the channel is
disconnected. This is a non consuming version of Receiver::recv
, but with a bit
worse performance. Prefer [
Receiver::recv]
if your code allows consuming the receiver.
If a message is returned, the channel is disconnected and any subsequent receive operation using this receiver will return an error.
§Panics
Panics if called after this receiver has been polled asynchronously.
Sourcepub fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError>
Available on crate feature std
only.
pub fn recv_timeout(&self, timeout: Duration) -> Result<T, RecvTimeoutError>
std
only.Like Receiver::recv
, but will not block longer than timeout
. Returns:
Ok(message)
if there was a message in the channel before the timeout was reached.Err(Timeout)
if no message arrived on the channel before the timeout was reached.Err(Disconnected)
if the sender was dropped before sending anything or if the message has already been extracted by a previous receive call.
If a message is returned, the channel is disconnected and any subsequent receive operation using this receiver will return an error.
If the supplied timeout
is so large that Rust’s Instant
type can’t represent this point
in the future this falls back to an indefinitely blocking receive operation.
§Panics
Panics if called after this receiver has been polled asynchronously.
Sourcepub fn recv_deadline(&self, deadline: Instant) -> Result<T, RecvTimeoutError>
Available on crate feature std
only.
pub fn recv_deadline(&self, deadline: Instant) -> Result<T, RecvTimeoutError>
std
only.Like Receiver::recv
, but will not block longer than until deadline
. Returns:
Ok(message)
if there was a message in the channel before the deadline was reached.Err(Timeout)
if no message arrived on the channel before the deadline was reached.Err(Disconnected)
if the sender was dropped before sending anything or if the message has already been extracted by a previous receive call.
If a message is returned, the channel is disconnected and any subsequent receive operation using this receiver will return an error.
§Panics
Panics if called after this receiver has been polled asynchronously.
Sourcepub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
Returns true if the associated Sender
was dropped before sending a message. Or if
the message has already been received.
If true
is returned, all future calls to receive methods are guaranteed to return
a disconnected error. And future calls to this method is guaranteed to also return true
.
Sourcepub fn has_message(&self) -> bool
pub fn has_message(&self) -> bool
Returns true if there is a message in the channel, ready to be received.
If true
is returned, the next call to a receive method is guaranteed to return
a message.
Sourcepub fn into_raw(self) -> *mut ()
pub fn into_raw(self) -> *mut ()
Consumes the Receiver, returning a raw pointer to the channel on the heap.
This is intended to simplify using oneshot channels with some FFI code. The only safe thing to do with the returned pointer is to later reconstruct the Receiver with Receiver::from_raw. Memory will leak if the Receiver is never reconstructed.
Sourcepub unsafe fn from_raw(raw: *mut ()) -> Self
pub unsafe fn from_raw(raw: *mut ()) -> Self
Consumes a raw pointer from Receiver::into_raw, recreating the Receiver.
§Safety
This pointer must have come from Receiver<T>::into_raw
with the same message type, T
.
At most one Receiver must exist for a channel at any point in time.
Constructing multiple Receivers from the same raw pointer leads to undefined behavior.