Struct thingbuf::mpsc::Receiver

pub struct Receiver<T, R = DefaultRecycle> { /* private fields */ }

This is supported on crate feature alloc only.

Asynchronously receives values from associated Senders.

Instances of this struct are created by the channel and with_recycle functions.

Implementations

impl<T, R> Receiver<T, R>

pub fn recv_ref(&self) -> RecvRefFuture<'_, T>

Receives the next message for this receiver, by reference.

This method returns None if the channel has been closed and there are no remaining messages in the channel’s buffer. This indicates that no further values can ever be received from this Receiver. The channel is closed when all Senders have been dropped.

If there are no messages in the channel’s buffer, but the channel has not yet been closed, this method will wait until a message is sent or the channel is closed.

This method returns a RecvRef that can be used to read from (or mutate) the received message by reference. When the RecvRef is dropped, the receive operation completes and the slot occupied by the received message becomes usable for a future send_ref operation.

If all Senders for this channel write to the channel’s slots in place by using the send_ref or try_send_ref methods, this method allows messages that own heap allocations to be reused in place.

Examples

use thingbuf::mpsc;
use std::fmt::Write;

#[tokio::main]
async fn main() {
    let (tx, rx) = mpsc::channel::<String>(100);
    tokio::spawn(async move {
        let mut value = tx.send_ref().await.unwrap();
        write!(value, "hello world!")
            .expect("writing to a `String` should never fail");
    });

    assert_eq!(Some("hello world!"), rx.recv_ref().await.as_deref().map(String::as_str));
    assert_eq!(None, rx.recv().await.as_deref());
}

Values are buffered:

use thingbuf::mpsc;
use std::fmt::Write;

#[tokio::main]
async fn main() {
    let (tx, rx) = mpsc::channel::<String>(100);

    write!(tx.send_ref().await.unwrap(), "hello").unwrap();
    write!(tx.send_ref().await.unwrap(), "world").unwrap();

    assert_eq!("hello", rx.recv_ref().await.unwrap().as_str());
    assert_eq!("world", rx.recv_ref().await.unwrap().as_str());
}

pub fn recv(&self) -> RecvFuture<'_, T, R> where
    R: Recycle<T>, 

Receives the next message for this receiver, by value.

This method returns None if the channel has been closed and there are no remaining messages in the channel’s buffer. This indicates that no further values can ever be received from this Receiver. The channel is closed when all Senders have been dropped.

If there are no messages in the channel’s buffer, but the channel has not yet been closed, this method will wait until a message is sent or the channel is closed.

When a message is received, it is moved out of the channel by value, and replaced with a new slot according to the configured recycling policy. If all Senders for this channel write to the channel’s slots in place by using the send_ref or try_send_ref methods, consider using the recv_ref method instead, to enable the reuse of heap allocations.

Examples

use thingbuf::mpsc;

#[tokio::main]
async fn main() {

    let (tx, rx) = mpsc::channel(100);

    tokio::spawn(async move {
        tx.send(1).await.unwrap();
    });

    assert_eq!(Some(1), rx.recv().await);
    assert_eq!(None, rx.recv().await);
}

Values are buffered:

use thingbuf::mpsc;

#[tokio::main]
async fn main() {
    let (tx, rx) = mpsc::channel(100);

    tx.send(1).await.unwrap();
    tx.send(2).await.unwrap();

    assert_eq!(Some(1), rx.recv().await);
    assert_eq!(Some(2), rx.recv().await);
}

pub fn poll_recv_ref(
    &self,
    cx: &mut Context<'_>
) -> Poll<Option<RecvRef<'_, T>>>

Attempts to receive a message by reference from this channel, registering the current task for wakeup if the a message is not yet available, and returning None if the channel has closed and all messages have been received.

Like Receiver::recv_ref, this method returns a RecvRef that can be used to read from (or mutate) the received message by reference. When the RecvRef is dropped, the receive operation completes and the slot occupied by the received message becomes usable for a future send_ref operation.

If all Senders for this channel write to the channel’s slots in place by using the send_ref or try_send_ref methods, this method allows messages that own heap allocations to be reused in place.

To wait asynchronously until a message becomes available, use the recv_ref method instead.

Returns

• Poll::Pending if no messages are available but the channel is not closed, or if a spurious failure happens.
• Poll::Ready(Some(RecvRef<T>)) if a message is available.
• Poll::Ready(None) if the channel has been closed (i.e., all Senders have been dropped), and all messages sent before it was closed have been received.

When the method returns Poll::Pending, the Waker in the provided Context is scheduled to receive a wakeup when a message is sent on any sender, or when the channel is closed. Note that on multiple calls to poll_recv_ref, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

pub fn poll_recv(&self, cx: &mut Context<'_>) -> Poll<Option<T>> where
    R: Recycle<T>, 

Attempts to receive a message by value from this channel, registering the current task for wakeup if the value is not yet available, and returning None if the channel has closed and all messages have been received.

When a message is received, it is moved out of the channel by value, and replaced with a new slot according to the configured recycling policy. If all Senders for this channel write to the channel’s slots in place by using the send_ref or try_send_ref methods, consider using the poll_recv_ref method instead, to enable the reuse of heap allocations.

To wait asynchronously until a message becomes available, use the recv method instead.

Returns

• Poll::Pending if no messages are available but the channel is not closed, or if a spurious failure happens.
• Poll::Ready(Some(message)) if a message is available.
• Poll::Ready(None) if the channel has been closed (i.e., all Senders have been dropped) and all messages sent before it was closed have been received.

When the method returns Poll::Pending, the Waker in the provided Context is scheduled to receive a wakeup when a message is sent on any sender, or when the channel is closed. Note that on multiple calls to poll_recv, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

pub fn is_closed(&self) -> bool

Returns true if the channel has closed (all corresponding Senders have been dropped).

If this method returns true, no new messages will become available on this channel. Previously sent messages may still be available.

Trait Implementations

impl<T: Debug, R: Debug> Debug for Receiver<T, R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, R> Drop for Receiver<T, R>

fn drop(&mut self)

Executes the destructor for this type.