Crate flo_stream

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

BlockingPublisher

A blocking publisher is a publisher that blocks messages until it has enough subscribers

ExpiringPublisher

An ‘expiring’ publisher is one that responds to backpressure from its subscribers by expiring the most recent message.

GeneratorStream

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.

MessageSender

A message sender represents a reserved space for sending a message. Because the space is reserved, the message can be sent immediately

Publisher

A publisher represents a sink that sends messages to zero or more subscribers

PublisherSink

An implementation of the Sink trait that can be applied to publishers

SinglePublisher

A single publisher is a publisher that sends each message to only a single subscriber rather than all of them

StreamPublisher

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.

StreamSwitch

Used to switch the stream for a corresponding SwitchingStream item

Subscriber

Represents a subscriber stream from a publisher sink

SwitchingStream

A stream that relays the results from a source stream, which can be switched out if necessary

WeakPublisher

A weak publisher republishes a Publisher only so long as that Publisher exists.

Traits

MessagePublisher

Trait that provides functions for publishing messages to subscribers

SendStreamToPublisher

Provides a way to send the values generated by a stream to a publisher

ToPublisherSink

Trait that turns publishers into sinks

Functions

generator_stream

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.

switchable_stream

Returns a switching stream and its switch, set to initially read from the stream that’s passed in