Trait postage::sink::Sink[−][src]

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: ?Sized> Future for SendFuture<'s, S> where
    S: Sink + Unpin,     type Output = Result<(), SendError<S::Item>>;
 { ... }

    fn try_send(
        &mut self, 
        value: Self::Item
    ) -> Result<(), TrySendError<Self::Item>>
    where
        Self: Unpin,
    { ... }

    fn blocking_send(
        &mut self, 
        value: Self::Item
    ) -> Result<(), SendError<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,
    { ... }

    fn log(self, level: Level) -> SinkLog<Self>
    where
        Self: Sized,
        Self::Item: Debug,
    { ... }
}

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

Associated Types

type Item[src]

Loading content...

Required methods

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

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.
Loading content...

Provided methods

fn send(&mut self, value: Self::Item) -> SendFuture<'_, Self>ⓘ

Notable traits for SendFuture<'s, S>

impl<'s, S: ?Sized> Future for SendFuture<'s, S> where
    S: Sink + Unpin,  type Output = Result<(), SendError<S::Item>>;
[src]

Attempts to send a message into the sink.

Returns:

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

fn try_send(
    &mut self,
    value: Self::Item
) -> Result<(), TrySendError<Self::Item>> where
    Self: Unpin, [src]

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.

fn blocking_send(
    &mut self,
    value: Self::Item
) -> Result<(), SendError<Self::Item>> where
    Self: Unpin, [src]

Sends a message over the channel, blocking the current thread until the message is sent.

Requires the blocking feature (enabled by default).

fn after<Before>(self, before: Before) -> ChainSink<Before, Self> where
    Before: Sink<Item = Self::Item>,
    Self: Sized, [src]

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

fn filter<Filter>(self, filter: Filter) -> FilterSink<Filter, Self> where
    Filter: FnMut(&Self::Item) -> bool,
    Self: Sized, [src]

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

fn log(self, level: Level) -> SinkLog<Self> where
    Self: Sized,
    Self::Item: Debug, [src]

Logs messages that are accepted by the sink using the Debug trait, at the provided log level.

Requires the logging feature

Loading content...

Implementations on Foreign Types

impl<S: ?Sized> Sink for &mut S where
    S: Sink + Unpin, [src]

type Item = S::Item

impl<P, S: ?Sized> Sink for Pin<P> where
    P: DerefMut<Target = S> + Unpin,
    S: Sink + Unpin, [src]

type Item = <S as Sink>::Item

Loading content...

Implementors

impl Sink for postage::barrier::Sender[src]

type Item = ()

impl<T> Sink for postage::broadcast::Sender<T> where
    T: Clone, [src]

type Item = T

impl<T> Sink for postage::dispatch::Sender<T>[src]

type Item = T

impl<T> Sink for postage::mpsc::Sender<T>[src]

type Item = T

impl<T> Sink for postage::oneshot::Sender<T>[src]

type Item = T

impl<T> Sink for postage::watch::Sender<T>[src]

type Item = T

Loading content...