Skip to main content

Module watch

Module watch 

Source
Expand description

watch((a, b, c)) — several method streams in, one stream out whose item is exactly the union of theirs (RETURNS-38).

use futures::{executor::block_on, stream, StreamExt};
use plexus_client::{watch, Watched3};

let tickets = stream::iter(vec![TicketsEvent]);
let chats = stream::iter(vec![ChatsEvent]);
let deployments = stream::iter(vec![DeployEvent]);

let mut s = watch((tickets, chats, deployments));
block_on(async {
    while let Some(it) = s.next().await {
        // No wildcard: the item is exactly one of the three.
        match it {
            Watched3::A(TicketsEvent) => {}
            Watched3::B(ChatsEvent) => {}
            Watched3::C(DeployEvent) => {}
        }
    }
});

Rust has no variadics, so the streams go in as a tuple: Watch is implemented for tuples of 2 to 12 streams, each giving its own WatchingN stream of WatchedN items — one variant per element, in the tuple’s order, holding that stream’s own item unchanged. A one-tuple is the stream itself.

§The rules

whenthen
items arrivethey come out as each stream yields them; a stream that is ready is never starved (the merge polls round-robin)
one stream endsit is dropped at once, and the merge goes on; it ends when all have
one stream yields an errorit is an item like any other (Watched3::B(Err(e)) — the variant names its source); the others go on
Errors::Stop (watch_with, or WatchingN::stop_on_error)the failing item is the last: every other stream is dropped with it and the merge ends
the merge is droppedevery stream it still holds is dropped, once each — over a WsTransport that is one call_unsub per live subscription

Nothing is new on the wire: each stream is the call it already was.

§The item is exact

Widening the union does not compile:

ⓘ
use futures::{executor::block_on, stream, StreamExt};
use plexus_client::{watch, Watched3};
struct A; struct B; struct C; struct Wide;
let mut s = watch((stream::iter(vec![A]), stream::iter(vec![B]), stream::iter(vec![C])));
let _: Option<Watched3<Wide, Wide, Wide>> = block_on(s.next());

Nor does watching nothing:

ⓘ
let _ = plexus_client::watch(());

A stream that is not Unpin (an async_stream block, say) goes in boxed: Box::pin(s). Every generated client stream already is.

Structs§

Watching2
The merge of a tuple of streams; see watch.
Watching3
The merge of a tuple of streams; see watch.
Watching4
The merge of a tuple of streams; see watch.
Watching5
The merge of a tuple of streams; see watch.
Watching6
The merge of a tuple of streams; see watch.
Watching7
The merge of a tuple of streams; see watch.
Watching8
The merge of a tuple of streams; see watch.
Watching9
The merge of a tuple of streams; see watch.
Watching10
The merge of a tuple of streams; see watch.
Watching11
The merge of a tuple of streams; see watch.
Watching12
The merge of a tuple of streams; see watch.

Enums§

Errors
What the merge does when one of its streams yields an error.
Watched2
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched3
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched4
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched5
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched6
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched7
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched8
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched9
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched10
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched11
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.
Watched12
One item of a merged stream: which stream it came from (the variant, in the tuple’s order) and that stream’s own item.

Traits§

Fallible
An item that may be a failure — what Errors::Stop looks at. Implemented for Result, which every client stream yields.
StopOnError
A merged stream that can be told to end at the first failure.
Watch
Several streams, given as a tuple, merged into one. See the module docs.

Functions§

watch
Merge the streams of a tuple into one: watch((a, b, c)).
watch_with
watch, with the policy for an error said up front.