Trait postage::sink::Sink

source · [−]
pub trait Sink {
    type Item;

    fn poll_send(
        self: Pin<&mut Self>, 
        cx: &mut Context<'_>, 
        value: Self::Item
    ) -> PollSend<Self::Item>;

    fn send(&mut self, value: Self::Item) -> SendFuture<'_, Self>ⓘNotable traits for SendFuture<'s, S>impl<'s, S> Future for SendFuture<'s, S> where
    S: Sink + Unpin + ?Sized,     type Output = Result<(), SendError<S::Item>>; { ... }
    fn try_send(
        &mut self, 
        value: Self::Item
    ) -> Result<(), TrySendError<Self::Item>>
    where
        Self: Unpin,
    { ... }
    fn after<Before>(self, before: Before) -> ChainSink<Before, Self>
    where
        Before: Sink<Item = Self::Item>,
        Self: Sized,
    { ... }
    fn filter<Filter>(self, filter: Filter) -> FilterSink<Filter, Self>
    where
        Filter: FnMut(&Self::Item) -> bool,
        Self: Sized,
    { ... }
}
Expand description

A sink which can asynchronously accept messages, and at some point may refuse to accept any further messages.

Sinks implement poll_send, a poll-based method very similar to std::future::Future.

Sinks can be used in async code with stream.send(value).await, or with stream.try_send(value). Note that send returns an error if the sink has been closed. And try_send returns an error if the sink is full, or it is closed.

Send errors can be ignored using Result::ok.

use postage::mpsc::channel;
use postage::sink::{Sink, TrySendError};

#[tokio::main]
async fn main() -> Result<(), TrySendError<bool>> {
    let (mut tx, mut rx) = channel(16);
    tx.send(true).await.ok();
    tx.try_send(true)?;
    drop(tx);
    Ok(())
}

Sinks also support combinators, such as map, filter, chain, and log.

use postage::mpsc::channel;
use postage::sink::{Sink, SendError, TrySendError};
use postage::stream::Stream;

#[tokio::main]
async fn main() {
    let (mut tx, mut rx) = channel(16);
    let (tx2, mut rx2) = channel(16);

    let mut combo = tx2
        .after(tx)
        .filter(|i| *i >= 2);
     
    // The `logging` feature enables a combinator that logs values using the Debug trait.
    #[cfg(feature = "logging")]
    let mut combo = combo
        .log(log::Level::Info);

    combo.send(1usize).await.ok();
    combo.send(2usize).await.ok();
    assert_eq!(Some(2usize), rx.recv().await);
    drop(rx);

    combo.send(3usize).await.ok();
    combo.send(4usize).await.ok();
    assert_eq!(Some(3usize), rx2.recv().await);
    assert_eq!(Some(4usize), rx2.recv().await);

    drop(rx2);
    assert_eq!(Err(SendError(5usize)), combo.send(5usize).await);
}

Required Associated Types

Required Methods

Attempts to accept the message, without blocking.

Returns:

  • PollSend::Ready if the value was sent
  • PollSend::Pending(value) if the channel is full. The channel will call the waker in cx when the item may be accepted in the future.
  • PollSend::Rejected(value) if the channel is closed, and will never accept the item.

Provided Methods

Attempts to send a message into the sink.

Returns:

  • Ok(()) if the value was accepted.
  • Err(SendError(value)) if the sink rejected the message.

Attempts to send a message over the sink, without blocking.

Returns:

  • Ok(()) if the value was accepted.
  • Err(TrySendError::Pending(value)) if the channel is full, and cannot accept the item at this time.
  • Err(TrySendError::Rejected(value)) if the channel is closed, and will never accept the item.

Chains two sink implementations. Messages will be transmitted to the argument until it rejects a message. Then messages will be transmitted to self.

Filters messages, forwarding them to the sink if the filter returns true

Implementations on Foreign Types

Implementors