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
| when | then |
|---|---|
| items arrive | they come out as each stream yields them; a stream that is ready is never starved (the merge polls round-robin) |
| one stream ends | it is dropped at once, and the merge goes on; it ends when all have |
| one stream yields an error | it 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 dropped | every 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::Stoplooks at. Implemented forResult, which every client stream yields. - Stop
OnError - 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.