Expand description
Reactive layer of ice-rpc: the stream vocabulary, the operators, the multicast primitive and the execution facade they need.
This crate is the foundation of ice-rpc. It owns Observable, Event,
ObservableError and RpcError, and it knows nothing about the wire:
no framing, no serialization format, no transport. ice-rpc depends on it and
re-exports every item under its historical path, so a consumer of ice-rpc
sees one single stream type and imports nothing new.
| Module | Contents |
|---|---|
event | Event, ObservableError and the producer-side Sender |
stream | Observable and the local channel constructors |
error | RpcError, the technical error of the whole stack |
creation | from, of, throw_error, defer, from_future, ObservableInput |
subject | Subject, the multicast source |
subscribe | Subscription, the cancellation handle — and the Future awaited to join it |
transform | the operators carried by Observable |
rt | execution facade and CancellationToken |
The operators are inherent methods on Observable: no extension trait to
import, one single stream type from the first operator to the last.
// `stream` is the native type returned by an ice-rpc service.
let stream: ice_rpc_rx::Observable<i32, String> = proxy.foo().await;
let odds = stream.filter(|v| *v % 2 == 1).map(|v| v * 10).take(5);
let first = odds.first_value().await?;Observable— the operators (map,filter,distinct_until_changed,map_err,scan,switch_map,take,skip,first,first_with,merge,start_with,tap,finalize,delay,timeout,catch_error,take_until,take_until_token) and the terminals (first_value,last_value,collect,for_each,subscribe,subscribe_all,next,recv). Every operator is a pull-based combinator: no intermediate channel, no spawned task. Each has its own reference, with a runnable example, onObservable.Subject— the push side: a multi-producer / multi-consumer multicast source.Subject::newmulticasts to the current subscribers,Subject::replayalso replays the lastnvalues (and the terminal state) to late subscribers.Observable::subscribe/Observable::subscribe_all— push-based consumption through RxJS-style callbacks.Subscriptionis the cancellation handle and aFuture:sub.awaitjoins the subscription, the shapeJoinHandleuses, while keeping the handle andunsubscribeing it is how a caller stops a stream early.from,of,throw_error— channel-free local constructors;deferandfrom_futuredefer their work to the first poll, so a service call is only issued when someone consumes the stream.ObservableInput— the bridge a projection uses to accept either anObservableor aFuturethat produces one, so anasync fnclient call composes without an explicitdefer(RxJSObservableInput).
§Operators
| ReactiveX category | Operators |
|---|---|
| Transforming | map, map_err, scan, switch_map |
| Filtering | filter, take, distinct_until_changed, skip, first, first_with |
| Combining | merge, start_with |
| Conditional / Boolean | take_until, take_until_token |
| Error handling | catch_error, retry_with |
| Utility | tap, finalize, delay, timeout |
| Terminals (they end the chain) | collect, first_value, last_value, for_each, subscribe, subscribe_all, next, recv |
Two rules hold for every operator: it is pull-based and lazy (it only
wraps its source in a boxed stream — no intermediate channel, no spawned
task), and it never drops or reorders a terminal event unless its own
documentation says otherwise. Only map_err and
catch_error act on the business error; a
technical RpcError is fatal and travels untouched.
§Normalization
A source may carry a single response as an internal single-sample
optimization. Observable::recv normalizes it into Next followed by
Complete, so consuming code always observes a uniform stream of Next
values followed by a terminal event (Complete or Error).
§Timeouts
Observable::timeout is a per-event silence watchdog on an
active stream, reset after every event.
Re-exports§
pub use rt::CancellationToken;
Modules§
- rt
- Execution facade: one full mode per host runtime, and a fallback for a deployment that has none.
Structs§
- Observable
- Consumer-side receiver of RPC events.
- Retry
Policy - Policy of
retry_with. - Sender
- Producer-side sender of stream events.
- Subject
- A multi-producer / multi-consumer multicast source.
- Subscription
- Handle of a running subscription.
Enums§
- Event
- Event emitted by a stream, as observed by consumers.
- Observable
Error - The single error type of the whole streaming API.
- RpcError
- Technical RPC error, categorized so callers can choose a policy
(retry / fallback / log / fatal) via
RpcError::is_retryable.
Traits§
- Observable
Input - Anything a combinator can accept as a source: an
Observableitself, or aFuturethat produces one.
Functions§
- channel
- Creates a bounded channel of RPC events.
- defer
- Creates an observable from a deferred factory (RxJS
defer). - from
- Creates an observable from an iterator, emitting each value as
NextthenComplete. - from_
future - Creates a one-value observable from a future (RxJS
from(promise)). - of
- Creates a single-value observable.
- retry_
with - Runs
factoryagain on every failure, up to the policy’s attempts (RxJSretry). - throw_
error - Creates an observable that only emits a business error.
- unbounded_
channel - Creates an unbounded channel of RPC events.