pub struct StaticReceiver<T: 'static, R: 'static = DefaultRecycle> { /* private fields */ }
Available on crate feature static only.
Expand description

Asynchronously receives values from associated StaticSenders.

Instances of this struct are created by the StaticChannel::split and ``StaticChannel::try_split` functions.

Implementations

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 StaticReceiver. The channel is closed when all StaticSenders 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 StaticSenders 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::StaticChannel;
use std::fmt::Write;

static CHANNEL: StaticChannel<String, 100> = StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

    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::StaticChannel;
use std::fmt::Write;

static CHANNEL: StaticChannel<String, 100> = StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

    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());
}

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 StaticReceiver. The channel is closed when all StaticSenders 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 StaticSenders 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::StaticChannel;

static CHANNEL: StaticChannel<i32, 100> = StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

    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::StaticChannel;

static CHANNEL: StaticChannel<i32, 100> = StaticChannel::new();

#[tokio::main]
async fn main() {
    let (tx, rx) = CHANNEL.split();

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

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

Attempts to receive the next message for this receiver by reference without waiting for a new message when the channel is empty.

This method differs from recv_ref by returning immediately if the channel is empty or closed.

Errors

This method returns an error when the channel is closed or there are no remaining messages in the channel’s buffer.

Examples
use thingbuf::mpsc::{channel, errors::TryRecvError};

let (tx, rx) = channel(100);
assert!(matches!(rx.try_recv_ref(), Err(TryRecvError::Empty)));

tx.try_send(1).unwrap();
drop(tx);

assert_eq!(*rx.try_recv_ref().unwrap(), 1);
assert!(matches!(rx.try_recv_ref(), Err(TryRecvError::Closed)));

Attempts to receive the next message for this receiver by reference without waiting for a new message when the channel is empty.

This method differs from recv by returning immediately if the channel is empty or closed.

Errors

This method returns an error when the channel is closed or there are no remaining messages in the channel’s buffer.

Examples
use thingbuf::mpsc::{channel, errors::TryRecvError};

let (tx, rx) = channel(100);
assert_eq!(rx.try_recv(), Err(TryRecvError::Empty));

tx.try_send(1).unwrap();
drop(tx);

assert_eq!(rx.try_recv().unwrap(), 1);
assert_eq!(rx.try_recv(), Err(TryRecvError::Closed));

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 StaticReceiver::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 StaticSenders 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 StaticSenders 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.

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 StaticSenders 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 StaticSenders 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.

Returns true if the channel has closed (all corresponding StaticSenders 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

Formats the value using the given formatter. Read more
Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.