IPC Transports & MPSC Adapter

Loading…

IPC Transports & MPSC Adapter

Relevant source files

• Cargo.lock
• extensions/muxio-tokio-mpsc-adapter/Cargo.toml
• extensions/muxio-tokio-mpsc-adapter/README.md
• extensions/muxio-tokio-mpsc-adapter/src/client.rs
• extensions/muxio-tokio-mpsc-adapter/src/lib.rs
• extensions/muxio-tokio-mpsc-adapter/src/server.rs
• extensions/muxio-tokio-rpc-ipc-client/Cargo.toml
• extensions/muxio-tokio-rpc-ipc-client/README.md
• extensions/muxio-tokio-rpc-ipc-client/src/lib.rs

This page covers the Muxio extension crates designed for local Inter-Process Communication (IPC) and the adapter layer that bridges Muxio’s streaming RPC events to standard Tokio asynchronous channels.

IPC Transports

Muxio provides native IPC support through muxio-tokio-rpc-ipc-client and muxio-tokio-rpc-ipc-server. These crates utilize the interprocess library to provide a cross-platform abstraction for local communication: Unix Domain Sockets on Linux/macOS and Named Pipes on Windows extensions/muxio-tokio-rpc-ipc-client/Cargo.toml15

RpcIpcClient

The RpcIpcClient implementation mirrors the architecture of the WebSocket client but targets local socket addresses. It implements RpcServiceCallerInterface, allowing it to be used interchangeably with other transports for making RPC calls extensions/muxio-tokio-rpc-ipc-client/src/lib.rs:5-7

MPSC Adapter

The muxio-tokio-mpsc-adapter crate provides a high-level convenience layer for streaming RPC. While the core RpcDispatcher uses callback-based event handling, this adapter allows developers to interact with streams using standard tokio::sync::mpsc channels extensions/muxio-tokio-mpsc-adapter/README.md3

ChannelCallerExt (Client-Side)

The ChannelCallerExt trait extends any RpcServiceCallerInterface (such as RpcClient or RpcIpcClient) to support channel-based streaming extensions/muxio-tokio-mpsc-adapter/src/client.rs15

Data Flow: open_channel

When open_channel is called, the following sequence occurs:

1. Validation : The client checks if the transport is active extensions/muxio-tokio-mpsc-adapter/src/client.rs:46-51
2. Channel Creation : Two mpsc::unbounded_channel pairs are created: one for the request stream and one for the response stream extensions/muxio-tokio-mpsc-adapter/src/client.rs:53-54
3. Dispatcher Call : The underlying RpcDispatcher::call is invoked. A recv_fn closure is registered to forward RpcStreamEvent::PayloadChunk events into the response channel extensions/muxio-tokio-mpsc-adapter/src/client.rs:73-92
4. Background Task : A Tokio task is spawned to monitor the request receiver. As the user sends Vec<u8> into the request channel, the task writes them to the RpcStreamEncoder and flushes extensions/muxio-tokio-mpsc-adapter/src/client.rs:116-126

ChannelEndpointExt (Server-Side)

The ChannelEndpointExt trait allows an RpcServiceEndpoint to register handlers that automatically pipe incoming stream data into an MPSC sender extensions/muxio-tokio-mpsc-adapter/src/server.rs:30-33

MpscSender Abstraction

To support both bounded and unbounded channels, the adapter defines the MpscSender trait extensions/muxio-tokio-mpsc-adapter/src/server.rs:13-15

• mpsc::Sender<Vec<u8>>: Uses try_send (may fail if buffer is full) extensions/muxio-tokio-mpsc-adapter/src/server.rs:17-21
• mpsc::UnboundedSender<Vec<u8>>: Uses send (always succeeds unless the receiver is dropped) extensions/muxio-tokio-mpsc-adapter/src/server.rs:23-27

Logic Association: Channel Mapping

The following diagram illustrates how Muxio RPC events are mapped to Tokio MPSC entities.

Code Entity Space: Client Channel Flow

This diagram shows the relationship between the ChannelCallerExt and the core RpcDispatcher.

Sources: extensions/muxio-tokio-mpsc-adapter/src/client.rs:35-130 extensions/muxio-tokio-mpsc-adapter/src/server.rs:50-80

graph TD
    subgraph "User Code Space"
        [UserApp] -- "open_channel(method_id)" --> [ChannelCallerExt]
        [UserApp] -- "send(Vec<u8>)" --> [req_tx]
        [resp_rx] -- "recv()" --> [UserApp]
    end

    subgraph "MPSC Adapter Space"
        [ChannelCallerExt] -- "spawns" --> [RequestTask]
        [RequestTask] -- "poll" --> [req_rx]
        [recv_fn] -- "send(Ok(bytes))" --> [resp_tx]
    end

    subgraph "Muxio Core Space"
        [RequestTask] -- "write_bytes()" --> [RpcStreamEncoder]
        [RpcDispatcher] -- "trigger(RpcStreamEvent)" --> [recv_fn]
    end

    [RpcStreamEncoder] -- "network I/O" --> [RemoteEndpoint]
    [RemoteEndpoint] -- "network I/O" --> [RpcDispatcher]

Code Entity Space: Server Handler Registration

This diagram describes how the server-side MPSC adapter bridges the RpcServiceEndpoint to a work queue.

Sources: extensions/muxio-tokio-mpsc-adapter/src/server.rs:50-80 extensions/muxio-tokio-mpsc-adapter/src/server.rs:13-27

graph LR
    subgraph "Endpoint Setup"
        [Endpoint] -- "register_channel_handler(tx)" --> [StreamHandlerClosure]
    end

    subgraph "Runtime Execution"
        [RpcDispatcher] -- "RpcStreamEvent::PayloadChunk" --> [StreamHandlerClosure]
        [StreamHandlerClosure] -- "try_send_bytes()" --> [MpscSender]
        [RpcStreamEvent::End] -- "None-ify" --> [Guard]
        [Guard] -- "drops" --> [MpscSender]
    end

    [MpscSender] -- "wakes" --> [WorkerTask]

Implementation Details

Lifecycle and Cleanup

The adapter ensures that resources are cleaned up when a stream ends:

1. Client Shutdown : When the user drops the req_tx (request sender), the background RequestTask receives None from req_rx, calls encoder.end_stream(), and terminates extensions/muxio-tokio-mpsc-adapter/src/client.rs:117-126
2. Server/Remote Shutdown : If the remote side sends an RpcStreamEvent::End or RpcStreamEvent::Error, the adapter clears the internal Option<Sender>. Dropping the sender causes the user’s receiver (resp_rx) to return None, signaling the end of the stream extensions/muxio-tokio-mpsc-adapter/src/client.rs:87-89 extensions/muxio-tokio-mpsc-adapter/src/server.rs:72-74

Use Case Matrix

Sources: extensions/muxio-tokio-mpsc-adapter/src/server.rs:42-49

Sources:

• extensions/muxio-tokio-rpc-ipc-client/Cargo.toml
• extensions/muxio-tokio-rpc-ipc-client/src/lib.rs
• extensions/muxio-tokio-mpsc-adapter/src/lib.rs
• extensions/muxio-tokio-mpsc-adapter/src/client.rs
• extensions/muxio-tokio-mpsc-adapter/src/server.rs