Expand description
ice-rpc — High-performance RPC framework over iceoryx2 shared memory.
§Overview
ice-rpc is a client/server RPC framework using iceoryx2 shared memory
as transport. From a simple Rust trait annotated with #[service],
the procedural macro automatically generates the entire IPC code:
client, server, proxy and lifecycle.
§Quick start
A complete, runnable example lives in examples/quickstart.rs: one file
holding the service, its provider and its consumer — the two roles picked by
a command-line argument. The steps below are that file.
§1. Define a service
use ice_rpc::{Observable, service};
/// The business error of the service.
///
/// `#[ice_rpc::payload]` supplies the rkyv derives (and `Debug`) — no `rkyv`
/// dependency of your own. The `serde` derives are the ones the optional `json`
/// and `http` features require on every service type.
#[ice_rpc::payload]
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum GreeterError {
/// The name was empty.
EmptyName,
}
#[service("GreeterService")]
pub trait GreeterService {
/// Returns a greeting for `name`.
async fn hello(&self, name: String) -> Observable<String, GreeterError>;
}The #[service("GreeterService")] macro automatically generates:
GreeterServiceRequest— rkyv enum for serializationGreeterServiceClient— IPC client (publish/subscribe, one call per request id)GreeterServiceServer— IPC server exposing the method dispatcherGreeterServiceProxy— unified entry point (3 modes)
§2. Start a Provider
struct Greeter;
#[ice_rpc::async_trait]
impl GreeterService for Greeter {
async fn hello(&self, name: String) -> Observable<String, GreeterError> {
if name.is_empty() {
// A business error is an observable too: it travels inside the flux.
return ice_rpc::throw_error(GreeterError::EmptyName);
}
// One value, then completion. A handler streaming several values uses
// the wire-level `ice_rpc::codegen::channel(capacity)`, which returns a
// `(Sender, Observable)` pair whose `send_complete_with` closes the
// stream with its last value.
ice_rpc::of(format!("Hello {name}!"))
}
}
#[ice_rpc::main(tokio)]
async fn main() {
// `#[ice_rpc::main]` owns the bootstrap (init + runtime) and the clean
// shutdown; `run_provider!` starts the services and waits for Ctrl+C.
if let Err(error) = ice_rpc::run_provider!(GreeterServiceProxy::provide(Greeter)).await {
log::error!("provider stopped: {error}");
}
}If an implementation calls locator().get() on a service of the same
process, declare it in dependencies(): the topological sort then initializes
the dependency first.
#[ice_rpc::main(tokio)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// ServiceBImpl calls ServiceA via locator().get(); both are local, so
// `ServiceBImpl::dependencies()` lists "ServiceA" and the sort runs
// ServiceA first.
ice_rpc::run_provider!(
ServiceAProxy::provide_with_init(ServiceAImpl::new()),
ServiceBProxy::provide_with_init(ServiceBImpl::new()),
).await
}A dependency provided by another process is external and never blocks the
startup: no discovery, no connection, no wait — see
ServiceInit::dependencies.
§3. Call from a Consumer
#[ice_rpc::main(tokio)]
async fn main() {
// Proxy instantiated lazily, IPC connection on the first RPC call.
let proxy = ice_rpc::locator()
.get::<GreeterServiceProxy>().await
.expect("GreeterService unknown");
match proxy.hello("Alice".into()).await.first_value().await {
Ok(greeting) => log::info!("{greeting}"),
Err(error) => log::error!("call failed: {error}"),
}
}§4. Provider and consumer in the same process
run_provider! never returns before shutdown: it awaits
wait_for_shutdown() and therefore blocks the task that calls it. Code
written after its .await, in the same task, runs only once the process is
stopping. To serve a provider and drive a Consumer (or any other work) in the
same main, spawn the provider and keep the caller free:
#[ice_rpc::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// `rt::spawn` works in every execution mode (rt-async / tokio / smol);
// under `#[ice_rpc::main(tokio)]`, `tokio::spawn` is the equivalent.
ice_rpc::rt::spawn(async {
if let Err(error) = ice_rpc::run_provider!(
CoreServiceProxy::provide(Core),
).await {
log::error!("provider stopped: {error}");
}
});
// Consumer side, on the main task.
let print = ice_rpc::locator().get::<PrintServiceProxy>().await.unwrap();
print.print().await.first_value().await?;
Ok(())
}A rt::block_on(run_provider!(..)) does not start the provider in the
background: block_on runs a future to completion on the calling thread, and
this future completes only on shutdown — such a call blocks until Ctrl+C.
§5. A blocking consumer, with no runtime at all
A small consumer that only issues a call needs neither an executor nor an
async main: #[ice_rpc::main(rt-none)] bootstraps ice-rpc around a plain
synchronous fn main and shuts it down with shutdown_blocking on exit.
The additive blocking surface — ServiceLocator::get_blocking,
Observable::first_value_blocking and the {method}_blocking twins a
#[service(..., blocking)] generates — needs neither .await nor
rt::block_on. The only auxiliary thread is the transport’s own response
dispatcher.
#[ice_rpc::main(rt-none)] // init + shutdown_blocking around a sync main
fn main() {
let proxy = ice_rpc::locator()
.get_blocking::<MyServiceProxy>()
.expect("the locator builds the proxy");
match proxy.hello_blocking("Alice".into()).first_value_blocking() {
Ok(value) => log::info!("Response: {value}"),
Err(e) => log::error!("call failed: {e}"),
}
}A complete program lives in examples/blocking-consumer-app.rs.
§6. Knowing whether a provider is connected
{Proxy}::is_provider_connected() answers, synchronously, whether a
provider is serving the service’s channel right now. The probe is read-only —
it opens the response direction of the channel without ever creating it — so
asking the question cannot make a service appear on the bus, and an unknown
channel answers Ok(false) instead of failing.
// A readiness check, or the decision to take a degraded path, without
// sending a request and waiting for the bounded provider wait.
if GreeterServiceProxy::is_provider_connected()? {
// A provider is on the channel: this call will not wait for one.
let greeting = proxy.hello("Alice".into()).await.first_value().await?;
} else {
log::warn!("GreeterService is not running");
}The answer is per channel (the group of #[service]): every service
that shares a group shares it, so it says whether some provider serves the
channel, not which service of it is answering. A true is therefore a
lower bound on availability, not a guarantee that this exact service is the
one running.
§7. Fire-and-forget methods
A method declared without a return type is a notification: one sample published, no answer, no terminal event. The generated caller is synchronous and reports only what the emitter can know — whether a subscriber took the sample:
#[service("LogSink", group = "logs")]
pub trait LogSink: Send + Sync + 'static {
/// One-way: no return type, so nothing is answered.
async fn push(&self, batch: Vec<LogRecord>);
/// Request/response: a stream of values comes back.
async fn tail(&self, count: u32) -> Observable<Vec<LogRecord>, LogError>;
}
let sink = ice_rpc::locator().get_blocking::<LogSinkProxy>()?;
match sink.push(batch) { // no `.await`: there is nothing to wait for
Ok(true) => {} // a subscriber took the sample
Ok(false) => drops += 1, // nobody was there, or the buffer was full
Err(e) => errors += 1, // the emission itself failed
}The two vocabularies cannot be confused: a method meant to answer produces a
value, so it cannot compile without its return type, and an explicit -> ()
is refused with both alternatives named. Ok(false) is an ordinary outcome
(best effort), Err is a real failure of the emission. On the provider side
the handler still reads its CallContext — so it inherits the caller’s
trace — but it cannot be cancelled: there is no call left to cancel.
Over the JSON transports a one-way method answers 202 Accepted, with
delivered reporting the same flag; no reply body is ever expected.
§Architecture
§Workspace crates
| Crate | Role |
|---|---|
ice-rpc-rx | Reactive layer: Observable, operators, Subject, execution facade |
ice-rpc | Core framework (protocol, transport, ServiceLocator) |
ice-rpc-macros | Procedural macros (#[service]) |
common | Example services (not shipped) |
gateway_nodejs | Node.js bridge (N-API) for the services |
§Key concepts
- Service : Rust trait annotated with
#[service("Name")]defining RPC methods - Node : process hosting one or more services, identified by its PID
- Observable : the composable stream returned by services; emits
Next/Complete/Error(ObservableError)where the error is either business (E) or technical (RpcError) - ServiceLocator : registry of the services the process provides, plus a lazy cache of the consumer proxies
- transport : iceoryx2 publish/subscribe, one channel per group of
services, correlated by an 8-byte request id (
ice_rpc::transport) - dispatch : one thread per channel receives the requests and polls each
handler once, on that thread. A handler that answers without yielding
completes there, exactly as if the transport had called it inline; one that
awaits is detached at its firstPendingand runs as a task on the execution facade, so a slow call never holds back the next request of the same channel - Proxy : unified entry point supporting 3 modes (Provider / Consumer / ProviderJson)
§Main modules
| Module | Role |
|---|---|
rx | The reactive layer, re-exported from ice-rpc-rx: operators, constructors and multicast primitives, all reachable from the Observable stream |
rt | Execution facade, re-exported from ice-rpc-rx: spawn, Spawner, sleep, block_on, cancellation |
types | Protocol types (RpcHeader, EventKind, WireEvent) and the reactive vocabulary re-exported from ice-rpc-rx |
transport | Publish/subscribe transport: one channel per service, correlation by id, streaming bridge |
locator | ServiceLocator : registration, lazy consumer proxies, lifecycle |
codegen | Internal contract for the generated code: wire types, provider primitives, constants, plumbing, dependency re-exports (doc-hidden) |
Modules§
- json
- The JSON contract of a service, in both directions.
- monitor
- Read-only observation surface used by the
ice-rpc-monitorobserver. - rt
- Execution facade, re-exported under its historical path.
- rx
- Reactive layer, re-exported under its historical path.
- trace
- Propagation seam between a call collector and the wire.
Macros§
- run_
provider - Starts the provider with the given services.
- start_
http_ gateway - Starts the HTTP REST gateway exposing the listed services.
Structs§
- Call
Context - Read-only view of the call being served, built from its request header.
- Cancellation
Token - A token that can be awaited and cancelled from any thread.
- Observable
- Consumer-side receiver of RPC events.
- Retry
Policy - Policy of
retry_with. - Service
Locator - Central registry of the application services (Service Locator pattern).
- Subject
- A multi-producer / multi-consumer multicast source.
- Subscription
- Handle of a running subscription.
- Trace
Context - Trace ids of one call.
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.
Constants§
- VERSION
- The
ice-rpcversion this build was compiled from.
Traits§
- Service
Init - Optional initialization trait that a business type can implement.
Functions§
- 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)). - is_
provider_ connected - Whether a provider is currently serving
channel. - locator
- Returns the global
ServiceLocator. - 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.
Attribute Macros§
- async_
trait - main
- Bootstraps ice-rpc around an
async fn main. - payload
#[payload]attribute macro: derives the traits an ice-rpc service payload needs, without the crate namingrkyv— and without its author having to ask forDebug.- service
#[service]attribute macro: generates the Proxy, Client, Server, and the lifecycle code for an RPC service trait.