ice-rpc
High-performance RPC framework over iceoryx2 shared memory: zero-copy header, rkyv payload, in-place decoding when the payload is aligned.
From a single #[service]-annotated trait, the procedural macro generates the entire IPC code: client, server, proxy and lifecycle. Automatic reconnection after a provider crash (including SIGKILL) is provided by iceoryx2's native node monitoring: the OS releases the node's monitoring file lock when the process dies, and Node::list reports it as NodeState::Dead.
Features
- Zero-copy IPC transport through iceoryx2 shared memory.
- Code generation with
#[service]: Request enum, Client, Server, Proxy and lifecycle. - Service discovery with a registry per node and dependency-aware topological initialization.
- Crash detection & reconnection without heartbeat (native iceoryx2 node monitoring).
- Three proxy modes:
Provider,Consumer,ProviderJson— the last one only when thejsonfeature is on. - Optional HTTP gateway (
httpplus onehttp-*adapter) built on trillium.http-tokioruns the server on the application's tokio runtime; thetrillium-smoladapters run it on the executor trillium embeds, while the ice-rpc tasks stay on the executor of the selected mode. The feature also generates the JSON view of every proxy (impl JsonInvoker) — the same one thejsonfeature emits, so the two transports cannot drift apart — which is also what keepsserde_json's conversion code out of a binary that never speaks JSON. - Optional JSON host surface (
jsonfeature):#[service]also generates the rkyv ↔serde_json::Valueconverters and theProviderJsonmode a JSON host dispatches to — thegateway_nodejsbridge today. Off by default: a Rust-only deployment does not carry them, and they are about half of the generated code of a service. - Optional out-of-band monitoring (
monitoringfeature):#[service]also generates a{Service}Decoder(andDisplayon the request enum) so an external observer renders the observed payloads in clear text — with each type'sDisplayimplementation when it has one, with itsDebugone otherwise. Off by default: a plain provider/consumer never calls that code. - Optional call tracing (
tracingfeature): the provider handler enters onetracingspan per call, carrying the ids the caller propagated (correlation, trace, span, parent) plus the service name and the method. The implementation's owntracing/logevents land in that span without it writing a line — and the ids are the framework's own, so no OpenTelemetry stack is needed to obtain them. A provider that delegates to another service of its own process is traced as well: the delegation gets a span of its own, markedkind = "local", and the callee reads its own identity instead of the caller's — while with the feature off that hop stays the plain in-process call it was, with no context and no allocation. Off by default: a deployment that collects no spans pays neither the dependency nor the span.examples/tracing-demo.rsshows both halves across two hops, one transported and one direct.
Installation
[]
= "0.3"
# Required to derive Archive/Serialize/Deserialize on your own types:
= { = "0.8", = ["std"] }
# Required by the code generated by #[service] (it references `::log`):
= "0.4"
The generated code references log directly (::log::…), and your own types derive rkyv traits, so both crates must be declared in your Cargo.toml.
Execution modes
The core names no runtime outside one façade (ice_rpc::rt). A façade
cannot be runtime-neutral: a detached task has to be polled by someone, and
"who polls" is the only thing a runtime is asked for here. So instead of one
lowest-common-denominator executor, there is one full mode per host runtime,
plus a fallback for a deployment that has none. "Full" means the process then
runs one pool, not three.
= { = "0.3" } # rt-threads (default)
= { = "0.3", = ["tokio"] } # tokio only
= { = "0.3", = ["smol"] } # smol only
| Mode | Task spawning, timers, blocking pool |
|---|---|
rt-threads (default) |
an async-executor instance owned by the crate, run by available_parallelism() OS threads (ICE_RPC_THREADS overrides the count), futures-timer for sleep, blocking for the pool. No third-party runtime, and no I/O reactor: the core performs no async I/O. |
tokio |
tokio::spawn, tokio::time::sleep, tokio's blocking pool |
smol |
smol::spawn on smol's global executor — so the tasks share the pool of an application that already runs smol — smol::Timer, smol::unblock. Set SMOL_THREADS: that executor runs one thread by default. |
The modes are exclusive: tokio + smol is a compile error. Enabling a mode
does not remove the fallback from the dependency graph, because Cargo features
are additive; a build that carries one runtime and nothing else says so:
= { = "0.3", = false, = ["tokio"] }
The two long-lived IPC loops own a std::thread and block on an iceoryx2
WaitSet: they never go through a runtime. #[ice_rpc::main] drives main
with ice_rpc::rt::block_on (no runtime required, any mode),
#[ice_rpc::main(tokio)] builds a multi-thread tokio runtime, and any
fn(Future) -> T can be given instead, e.g.
#[ice_rpc::main(pollster::block_on)].
- Service methods return
ice_rpc::Observable<T, E>. Build one with the stream constructors of the Rx layer (of,from,throw_error,Subject); an advanced provider may use the raw channel viaice_rpc::gen::channel::<T, E>(capacity). ice_rpc::rtexposesspawn,spawn_blocking,blocking_call,sleep,block_on,oneshotandCancellationToken. A response deadline is not one of them: it is thetimeoutoperator on the stream a call returns.
Quick start
1. Define a service
use ;
use ;
The macro generates MyServiceRequest, MyServiceClient, MyServiceServer, MyServiceProxy and MyServiceMode.
#[service] also accepts two optional parameters:
version(integer, default1) — service interface version carried in the RPC header. An incompatible peer is rejected withRpcError::IncompatibleVersion;group(string, default: the service name) — the channel shared with the other services of the same group: one request channel, one response channel and one dispatch thread, with the samples routed by the service id.
2. Start a provider
;
async
3. Call from a consumer
async
Core concepts
| Concept | Description |
|---|---|
Observable<T, E> |
The composable stream, and the return type of service methods (no Result). |
Event<T, E> |
Consumer-facing: Next(T) / Complete / Error(ObservableError<E>) where ObservableError is Business(E) or Technical(RpcError). |
ObservableError<E> |
Terminal error of first_value(): Business(E) / Technical(RpcError) / Empty. |
ServiceLocator |
Global registry, reached through locator(): locator().get::<MyProxy>(). |
ServiceInit |
The only trait a developer implements: dependencies() + the on_init hook. |
Proxy |
Single entry point with 3 modes (Provider / Consumer / ProviderJson). |
Internal concepts (NodeId, WireEvent, the transport entry points, …) are
exposed through the doc-hidden ice_rpc::gen module and used by
ice-rpc-macros. The transport itself is a publish/subscribe pair of channels
per service, correlated by a 16-byte id: see ice_rpc::transport.
Consumption
Consuming a stream is done natively on ice_rpc::Observable, whose operators are
inherent methods (nothing to import); a call never fails at the call site — a
connection/transport failure becomes an in-stream technical error:
let value = proxy.hello.await.first_value.await?;
let all = proxy.list.await.collect.await?; // Vec<T>
first_value() -> Result<T, ObservableError<E>>(Emptywhen the stream completes without a value);collect() -> Result<Vec<T>, ObservableError<E>>;last_value() -> Result<T, ObservableError<E>>(the counterpart offirst_value, with the sameEmptyshape and one slot held instead of the whole sequence);- the
timeoutandtake_untiloperators bound the response wait and cancel a stream; - the operators documented on
Observableare all available as inherent methods: transforming (map,map_err,scan,switch_map), filtering (filter,take,distinct_until_changed,skip,first,first_with), combining (merge,start_with), conditional (take_until), error handling (catch_error) and utility (tap,finalize,delay,timeout). Each method documents its semantics and ships a runnable example — see theObservableAPI documentation; - dropping a response stream whose call is still in flight cancels the call on
the provider: the handler's future is dropped, so the work stops instead of
running on for a caller that no longer listens. A call whose terminal event was
read is released silently — nothing is sent. The implementation honours the
signal by reading
CallContext::cancellation();examples/remote_cancel.rsshows both halves.
Error semantics
Errors travel inside the flux. Event::Error(ObservableError<E>) carries
either a business error (Business(E)) or a technical one
(Technical(RpcError)), so a single match detects a failure and the caller
refines with the two variants.
RpcError classifies technical failures so callers can choose a policy
(retry / fallback / log / fatal) via
RpcError::is_retryable().
Every variant the enum declares, in declaration order:
| Variant | Meaning | Retryable |
|---|---|---|
SerializationError |
rkyv serialization/deserialization failure | no |
TransportError |
iceoryx2 I/O failure (loan, send, receive, port creation) | yes |
Timeout |
deadline exceeded | yes |
Cancelled |
cancelled by a global shutdown (SIGINT/SIGTERM or programmatic), a take_until token or a timeout; a remote Cancel published by a consumer that abandoned the call is handled by the provider and stays silent |
no |
Internal |
unexpected internal error / invariant violation | no |
ProtocolMismatch |
the service on the bus was recorded with a different configuration — a peer resolving another iceoryx2.toml, or another build — or its state was left behind by a process killed while it held it; no amount of retrying resolves it — see docs/wire-compat.md |
no |
UnknownMethod |
the provider has no method of that name on the requested service; answered at once, so a typo or a stale client is diagnosable instead of ending in a transport timeout | no |
UnknownService |
no service is registered under the requested id on that channel; answered at once too, and it names the id in hexadecimal because a hash cannot be inverted | no |
IncompatibleVersion |
the provider was built with another #[service(version = N)]; emitted before the payload is decoded, and no amount of retrying resolves it — both peers must be rebuilt with the same declared version |
no |
Four names that appeared in an earlier version of this table — DiscoveryError,
ProviderUnavailable, ServiceNotFound, PayloadTooLarge — have no variant.
ServiceNotFound is not UnknownService above: the latter is real, and it names an
id with no dispatcher on the channel, not a service the locator failed to find.
Addressing is static: a provider that is not running is not a distinct error, it
surfaces as a TransportError reading no subscriber connected once the provider
wait (ICE_RPC_PROVIDER_WAIT_MS, 30 s) elapses, and an oversized payload as an
iceoryx2 failure. A match on RpcError is exhaustive, so the compiler settles the
question rather than this table.
Service initialization
Implement ServiceInit on your service type to declare dependencies and run an initialization hook:
For services that consume other services, register with provide_with_init. #[ice_rpc::main] bootstraps ice-rpc (init + runtime) and owns the clean shutdown, while run_provider! starts the services and waits for Ctrl+C:
run_provider!.await
Clean shutdown
#[ice_rpc::main] shuts ice-rpc down for you, including on an early return or
?:
async
For a hand-written main (one calling std::process::exit, the N-API gateway,
tests), the lifecycle lives in ice_rpc::gen: let guard = ice_rpc::gen::init();
… guard.shutdown().await;.
HTTP gateway (optional)
Enable the http feature and one adapter, http-<mode>: trillium needs one,
and letting the bare feature pick would contradict the mode chosen above.
= { = "0.3", = ["tokio", "http-tokio"] }
= { = "0.3", = ["smol", "http-smol"] }
= { = "0.3", = ["http-threads"] } # the default mode
async
Services are then reachable through /{service}/{method}.
Configuration
ice-rpc does not own the iceoryx2 configuration and never writes a config
file: the effective configuration is the one iceoryx2 resolves itself. iceoryx2
looks for ./config/iceoryx2.toml first, then the user config directory, then
the global config directory, and falls back to its compiled-in default when none
exists.
Two processes communicate only if they agree on the root path (the shared-memory
domain). Provide a ./config/iceoryx2.toml — or a user/global one — when the
default is not what you want; every peer that discovers the same file shares the
domain. A partial file is enough: iceoryx2 merges it over its defaults.
Every participant must share the same configuration
The service limits — publishers, subscribers, nodes, subscriber buffer size and
loaned samples — are not hard-coded by ice-rpc: they come from the iceoryx2
configuration, so the deployment owns them. This widens the coherence rule above:
all participants of a channel must resolve the same iceoryx2 configuration.
When they do not, ice-rpc reports a protocol mismatch that names the two cases
— a divergent configuration, or leftover state from a killed process — each with
its own remedy.
The same protocol version is required; the same build is not. A consumer and a provider built from different revisions interoperate as long as they speak the same protocol version and resolve the same configuration, which is what lets one side be upgraded before the other.
iceoryx2's compiled-in defaults are conservative (max-publishers = 2,
max-subscribers = 8, subscriber-max-buffer-size = 2, …). When no
configuration file is present they apply, so ship a baseline that restores the
values ice-rpc used to pin. It must sit in ./config/iceoryx2.toml relative to
the working directory of each process — iceoryx2 resolves it from there, so
cargo test and cargo run look in the package directory, not the workspace
root. This workspace ships one for its own tests and examples under
ice-rpc/config/ and ice-rpc-macros-tests/config/:
[]
= 16
= 16
= 32
= 1024
= 1024
Slice length
The one publisher setting iceoryx2 does not expose in its configuration is the
initial slice length, and its builder default is 1 — with the default
publisher-allocation-strategy = "Static" that is a hard cap, so a 1-element
slice cannot carry an RPC payload. It is therefore declared by the service, per
channel:
Every service of a group must declare the same max_slice_len; an omitted value
falls back to DEFAULT_MAX_SLICE_LEN (256). Setting
publisher-allocation-strategy = "PowerOfTwo" in the configuration lets a
publisher grow past that initial size instead of refusing the sample.
Process allocator
A request that carries a struct the service takes by value (async fn
search(&self, query: WorkloadQuery)) is deserialized, and rkyv pays one
allocation per variable field to do it — the same for a String argument, or
for the list a caller builds before the call. On a request with ~130 variable
fields that is 130 malloc/free pairs per call, and the process allocator
becomes the dominant cost:
| one process, one line changed | system allocator | mimalloc |
|---|---|---|
| provider serving a struct of ~130 variable fields | 62 481 req/s | 138 032 req/s |
| caller building 256 string fields | 83 717 req/s | 141 618 req/s |
A response pays it twice — once by the provider that builds the value, once by
the caller that decodes it — and no signature can avoid that, since a stream hands
out owned values. The same 64-field structure runs at 19 434 req/s as a return
value, against 139 854 as a request and 283 668 for a scalar call (40 733 /
211 429 / 341 074 with mimalloc). A large structured response is therefore a
design choice: splitting it into several small ones costs a fraction of that.
ice-rpc never picks an allocator; the binary does:
static ALLOCATOR: MiMalloc = MiMalloc;
Both demo binaries carry it for that reason, and the three-way measurement (provider only, caller only, both) is what the two rows above come from: the allocator is a property each side decides for itself.
The allocations themselves cannot be avoided from the outside: an archive holds the archived form of a value, so the provider rebuilds every owned field, and a stream hands the caller owned values. What the numbers above price is that, and the levers left are the allocator (above) and the shape of the exchange — a response split into several small ones, or a request that carries fewer variable fields.
License
Apache-2.0