Skip to main content

Crate ice_rpc

Crate ice_rpc 

Source
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 serialization
  • GreeterServiceClient — IPC client (publish/subscribe, one call per request id)
  • GreeterServiceServer — IPC server exposing the method dispatcher
  • GreeterServiceProxy — 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

CrateRole
ice-rpc-rxReactive layer: Observable, operators, Subject, execution facade
ice-rpcCore framework (protocol, transport, ServiceLocator)
ice-rpc-macrosProcedural macros (#[service])
commonExample services (not shipped)
gateway_nodejsNode.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 first Pending and 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

ModuleRole
rxThe reactive layer, re-exported from ice-rpc-rx: operators, constructors and multicast primitives, all reachable from the Observable stream
rtExecution facade, re-exported from ice-rpc-rx: spawn, Spawner, sleep, block_on, cancellation
typesProtocol types (RpcHeader, EventKind, WireEvent) and the reactive vocabulary re-exported from ice-rpc-rx
transportPublish/subscribe transport: one channel per service, correlation by id, streaming bridge
locatorServiceLocator : registration, lazy consumer proxies, lifecycle
codegenInternal 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-monitor observer.
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§

CallContext
Read-only view of the call being served, built from its request header.
CancellationToken
A token that can be awaited and cancelled from any thread.
Observable
Consumer-side receiver of RPC events.
RetryPolicy
Policy of retry_with.
ServiceLocator
Central registry of the application services (Service Locator pattern).
Subject
A multi-producer / multi-consumer multicast source.
Subscription
Handle of a running subscription.
TraceContext
Trace ids of one call.

Enums§

Event
Event emitted by a stream, as observed by consumers.
ObservableError
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-rpc version this build was compiled from.

Traits§

ServiceInit
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 Next then Complete.
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 factory again on every failure, up to the policy’s attempts (RxJS retry).
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 naming rkyv — and without its author having to ask for Debug.
service
#[service] attribute macro: generates the Proxy, Client, Server, and the lifecycle code for an RPC service trait.