ice-rpc
High-performance, zero-copy RPC framework over iceoryx2 shared memory.
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 a cross-platform kernel watchdog (Windows Mutex / Unix flock).
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 (kernel named lock).
- Three proxy modes:
Provider,Consumer,ProviderNodeJs. - Optional HTTP gateway (
httpfeature) built on trillium (runtime-agnostic, no tokio required). - Optional consumer-side TTL cache (
cachefeature) via the#[cache(ttl = "60s")]method attribute.
Installation
[]
= "0.1"
# 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.
Runtime-agnostic
The ice-rpc core has no dependency on a specific async runtime. By
default, the execution facade (ice_rpc::rt) is backed by
async-global-executor (task spawning), std::thread (blocking IPC threads)
and futures-timer (timers), so it runs on any executor: tokio, smol,
or even pollster.
Optional Cargo features switch the facade to a dedicated runtime:
= { = "0.1" } # agnostic (default)
= { = "0.1", = ["smol"] } # smol (native facade)
= { = "0.1", = ["tokio"] } # tokio facade
= { = "0.1", = ["http"] } # trillium gateway (runtime-agnostic)
= { = "0.1", = ["cache"] } # consumer-side TTL cache
= { = "0.1", = ["full"] } # http + cache + tokio
full is a convenience feature that enables http, cache and tokio in one shot.
- Service methods return
ice_rpc::Stream<T, E>— anasync_channel::Receiver. Create the stream withice_rpc::channel::<T, E>(capacity). ice_rpc::rtexposesspawn,spawn_blocking,sleep,timeout,block_on,oneshotandCancellationToken.
Quick start
1. Define a service
use ;
use ;
The macro generates MyServiceRequest, MyServiceClient, MyServiceServer, MyServiceProxy and MyServiceMode.
#[service] also accepts three optional parameters:
allow_large_payload(bool, defaultfalse) — creates the second shared-memory segment (_large) for payloads aboveLARGE_PAYLOAD_THRESHOLD;default_size_message(integer, in KiB) — initial slice size of the_defaultshared-memory segment publisher;version(integer, default1) — service interface version carried in the RPC header. An incompatible peer is rejected withRpcError::IncompatibleVersion.
2. Start a provider
;
async
3. Call from a consumer
async
Core concepts
| Concept | Description |
|---|---|
NodeId |
Process identity (PID), unique across the machine. |
Observable<T, E> |
RPC stream: Result<Receiver<Event<T, E>>, RpcError>. |
Event<T, E> |
Next(T) / Complete / Error(E) / RpcError(RpcError). |
ConnectionState |
Client connection state machine (Unknown / Discovering / Ready / Dead / Reconnecting). |
ServiceLocator |
Global registry, dependency resolution and initialization. |
NodeHub |
Central IPC hub: publishers, request/response handlers, dispatch loop. |
Proxy |
Single entry point with 3 modes (Provider / Consumer / ProviderNodeJs). |
Consumption helpers
take_one!(observable)andtake_one_or_cancel!(observable, cancel)extract the first value of a stream.#[timeout("30s")]on a method sets the service-location timeout (defaultRPC_CALL_TIMEOUT_SECS= 30s).
Error semantics
RpcError classifies technical failures so callers can choose a policy
(retry / fallback / log / fatal) via RpcError::is_retryable().
| Variant | Meaning | Retryable |
|---|---|---|
TransportError |
iceoryx2 I/O failure | yes |
DiscoveryError |
discovery cycle failure | yes |
ProviderUnavailable |
provider node unreachable | yes |
Timeout |
deadline exceeded | yes |
ServiceNotFound |
service not registered on any node | no |
Cancelled |
global shutdown (Ctrl+C) | no |
SerializationError |
rkyv serialization/deserialization failure | no |
PayloadTooLarge |
payload above the shared-memory limit | no |
ProtocolMismatch |
incompatible protocol/service version | no |
Internal |
unexpected internal error | no |
Service initialization
Implement ServiceInit on your service type to declare dependencies and run an initialization hook:
For services that consume other services, initialize with init() and register with provide_with_init:
init;
run_provider!.await
Clean shutdown
Use the RAII ShutdownGuard to cancel the IPC threads on drop and, on success path, wait for their termination:
let guard = new;
// ... use ice-rpc ...
guard.shutdown.await; // waits for the IPC threads and releases the iceoryx2 node
Consumer-side cache (optional)
Enable the cache feature:
= { = "0.1", = ["cache"] }
Then annotate a service method with #[cache(ttl = "60s")]. On the consumer
side, the generated client caches successful Next values keyed by the
serialized arguments, so subsequent identical calls skip the IPC round-trip
until the TTL expires.
use ;
ttl— lifetime of a cached entry (e.g."60s","5min");max_entries— optional maximum number of entries (default1024).
The cache is a local, thread-safe RpcCache (ice_rpc::RpcCache) with lazy
expiry; it is intended for idempotent reads.
HTTP gateway (optional)
Enable the http feature:
= { = "0.1", = ["http"] }
init;
start_http_gateway!.await;
Services are then reachable through /{service}/{method}.
Configuration
The iceoryx2 root path is resolved in this order:
ICE_RPC_ROOT_PATHenvironment variable (explicit override);%APPDATA%\ice-rpc\iceoryx2on Windows,$XDG_DATA_HOME/ice-rpc/iceoryx2(or~/.local/share/ice-rpc/iceoryx2) on Unix;- iceoryx2 default.
License
Apache-2.0