Crate flo_stream[−][src]
Expand description
flo_stream
is a crate providing some extra utilities for streams in Rust’s futures
library, in particular the ‘pubsub’ pattern.
The primary new feature is a “pubsub” mechanism - a way to subscribe to updates sent to a futures Sink
. This differs
from the Sender
/Receiver
mechanism provided in the main futures library in two key ways: it’s possible to have
multiple receivers, and messages sent when there is no subscriber connected will be ignored.
PubSub
The sink type provided is Publisher
. You can create one with let publisher = Publisher::new(10)
. This implements
the Sink
trait so can be used in a very similar way to send messages. The number passed in is the maximum number
of waiting messages allowed for any given subscriber.
A subscription can be created using let subscription = publisher.subscribe()
. Any messages sent to the sink after
this is called is relayed to all subscriptions. A subscription is a Stream
so can interact with other parts of the
futures library in the usual way.
Here’s a full worked example with a single subscriber.
let mut publisher = Publisher::new(10);
let mut subscriber = publisher.subscribe();
executor::block_on(async {
publisher.publish(1).await;
publisher.publish(2).await;
publisher.publish(3).await;
assert!(subscriber.next().await == Some(1));
assert!(subscriber.next().await == Some(2));
assert!(subscriber.next().await == Some(3));
});
Structs
A blocking publisher is a publisher that blocks messages until it has enough subscribers
An ‘expiring’ publisher is one that responds to backpressure from its subscribers by expiring the most recent message.
A generator stream is a stream that runs a Future internally that generates multiple results, which are formatted as a stream. The stream is closed when the future terminates.
A message sender represents a reserved space for sending a message. Because the space is reserved, the message can be sent immediately
A publisher represents a sink that sends messages to zero or more subscribers
An implementation of the Sink trait that can be applied to publishers
A single publisher is a publisher that sends each message to only a single subscriber rather than all of them
The StreamPublisher
struct sends a stream to a publisher. It implements the Future
trait, and
will return an empty value when the entire stream has been sent to the publisher.
Used to switch the stream for a corresponding SwitchingStream
item
Represents a subscriber stream from a publisher sink
A stream that relays the results from a source stream, which can be switched out if necessary
A weak publisher republishes a Publisher
only so long as that Publisher
exists.
Traits
Trait that provides functions for publishing messages to subscribers
Provides a way to send the values generated by a stream to a publisher
Trait that turns publishers into sinks
Functions
Creates a new generator stream: this is a stream where the items are generated by a future, which can yield them to be returned by the stream via the function that’s passed in. This is useful for cases where a stream’s values are generated by complicated, stateful behaviour.
Returns a switching stream and its switch, set to initially read from the stream that’s passed in