# cloudwego/shmipc-rs architecture

> Architecture diagram of the GitHub repository cloudwego/shmipc-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudwego/shmipc-rs
- Repository: https://github.com/cloudwego/shmipc-rs

## Overview

Shmipc is a Rust library for zero-copy, batched inter-process communication over shared memory, synchronized through Unix-domain or TCP connections. Applications obtain logical streams from a session manager or accept them through a listener; peers negotiate protocol settings, map shared-memory buffers and queues, then exchange stream data and wakeups. The README documents legacy V2/V3 and opt-in V4 modes, including eventfd and polling wakeups. Some subsystem links rely on documented behavior because their implementation was not sampled.

Main entry points: [`src/session/mod.rs`](https://github.com/cloudwego/shmipc-rs/blob/main/src/session/mod.rs) (Session), [`src/session/manager.rs`](https://github.com/cloudwego/shmipc-rs/blob/main/src/session/manager.rs) (Session manager), [`src/protocol/initializer/mod.rs`](https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/initializer/mod.rs) (Protocol initializer), [`src/queue.rs`](https://github.com/cloudwego/shmipc-rs/blob/main/src/queue.rs) (Shared I/O queues)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_listener["Listener<br/>[listener.rs]"]
  node_transport["Connection transport<br/>[transport.rs]"]
end

subgraph group_session["Sessions and Streams"]
  node_manager["Session manager<br/>[manager.rs]"]
  node_session["Session<br/>[mod.rs]"]
  node_stream["Logical stream<br/>[stream.rs]"]
  node_pool["Stream pool<br/>[pool.rs]"]
  node_stats["Session statistics<br/>[stats.rs]"]
end

subgraph group_protocol["Protocol Setup"]
  node_protocol["Protocol setup<br/>[mod.rs]"]
  node_initializer["Protocol initializer<br/>[mod.rs]"]
  node_negotiation["Feature negotiation<br/>[negotiation.rs]"]
  node_protocol_versions["V2 / V3 / V4"]
end

subgraph group_shared["Shared-Memory I/O"]
  node_buffers[("Buffer manager<br/>[manager.rs]")]
  node_buffer_slices["Buffer slices<br/>[slice.rs]"]
  node_linked_buffer["Linked buffers<br/>[linked.rs]"]
  node_queue[("Shared I/O queues<br/>[queue.rs]")]
  node_wakeups["Wakeup mechanisms<br/>[event.rs]"]
end

node_client(("Client application"))
node_server(("Server application"))
node_peer(("Remote process"))

node_client -->|"requests streams"| node_manager
node_server -->|"accepts streams"| node_listener
node_manager -->|"connects peer"| node_transport
node_transport -->|"opens connection"| node_peer
node_listener -->|"accepts connection"| node_transport
node_manager -->|"creates sessions"| node_session
node_manager -->|"rebuilds sessions"| node_session
node_manager -->|"obtains streams"| node_pool
node_session -->|"initializes protocol"| node_initializer
node_initializer -->|"negotiates V4"| node_negotiation
node_negotiation -->|"selects mode"| node_protocol_versions
node_initializer -->|"handles legacy setup"| node_protocol_versions
node_protocol -->|"creates or maps"| node_buffers
node_protocol -->|"creates or maps"| node_queue
node_initializer -->|"maps peer memory"| node_buffers
node_initializer -->|"maps peer queue"| node_queue
node_session -->|"dispatches queue events"| node_queue
node_session -->|"sends and receives wakeups"| node_wakeups
node_stream -->|"reads and writes"| node_linked_buffer
node_linked_buffer -->|"uses slices"| node_buffer_slices
node_buffer_slices -->|"allocates and recycles"| node_buffers
node_stream -->|"enqueues stream data"| node_queue
node_session -->|"routes incoming streams"| node_stream
node_session -->|"reuses streams"| node_pool
node_session -->|"updates counters"| node_stats
node_negotiation -.->|"selects optional mode"| node_wakeups

click node_listener "https://github.com/cloudwego/shmipc-rs/blob/main/src/listener.rs"
click node_transport "https://github.com/cloudwego/shmipc-rs/blob/main/src/transport.rs"
click node_manager "https://github.com/cloudwego/shmipc-rs/blob/main/src/session/manager.rs"
click node_session "https://github.com/cloudwego/shmipc-rs/blob/main/src/session/mod.rs"
click node_stream "https://github.com/cloudwego/shmipc-rs/blob/main/src/stream.rs"
click node_pool "https://github.com/cloudwego/shmipc-rs/blob/main/src/session/pool.rs"
click node_stats "https://github.com/cloudwego/shmipc-rs/blob/main/src/stats.rs"
click node_protocol "https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/mod.rs"
click node_initializer "https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/initializer/mod.rs"
click node_negotiation "https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/negotiation.rs"
click node_protocol_versions "https://github.com/cloudwego/shmipc-rs/tree/main/src/protocol/initializer"
click node_buffers "https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/manager.rs"
click node_buffer_slices "https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/slice.rs"
click node_linked_buffer "https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/linked.rs"
click node_queue "https://github.com/cloudwego/shmipc-rs/blob/main/src/queue.rs"
click node_wakeups "https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/event.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_listener,node_transport,node_client toneBlue
class node_manager,node_session,node_stream,node_pool,node_stats toneAmber
class node_protocol,node_initializer,node_negotiation,node_protocol_versions,node_server toneMint
class node_buffers,node_buffer_slices,node_linked_buffer,node_queue,node_wakeups toneRose
class node_peer toneIndigo
```

## Components

### Application API

- [Listener](https://github.com/cloudwego/shmipc-rs/blob/main/src/listener.rs): `src/listener.rs`
- [Connection transport](https://github.com/cloudwego/shmipc-rs/blob/main/src/transport.rs): `src/transport.rs`

### Sessions and Streams

- [Session manager](https://github.com/cloudwego/shmipc-rs/blob/main/src/session/manager.rs): `src/session/manager.rs`
- [Session](https://github.com/cloudwego/shmipc-rs/blob/main/src/session/mod.rs): `src/session/mod.rs`
- [Logical stream](https://github.com/cloudwego/shmipc-rs/blob/main/src/stream.rs): `src/stream.rs`
- [Stream pool](https://github.com/cloudwego/shmipc-rs/blob/main/src/session/pool.rs): `src/session/pool.rs`
- [Session statistics](https://github.com/cloudwego/shmipc-rs/blob/main/src/stats.rs): `src/stats.rs`

### Protocol Setup

- [Protocol setup](https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/mod.rs): `src/protocol/mod.rs`
- [Protocol initializer](https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/initializer/mod.rs): `src/protocol/initializer/mod.rs`
- [Feature negotiation](https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/negotiation.rs): `src/protocol/negotiation.rs`
- [V2 / V3 / V4](https://github.com/cloudwego/shmipc-rs/tree/main/src/protocol/initializer): `src/protocol/initializer`

### Shared-Memory I/O

- [Buffer manager](https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/manager.rs): `src/buffer/manager.rs`
- [Buffer slices](https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/slice.rs): `src/buffer/slice.rs`
- [Linked buffers](https://github.com/cloudwego/shmipc-rs/blob/main/src/buffer/linked.rs): `src/buffer/linked.rs`
- [Shared I/O queues](https://github.com/cloudwego/shmipc-rs/blob/main/src/queue.rs): `src/queue.rs`
- [Wakeup mechanisms](https://github.com/cloudwego/shmipc-rs/blob/main/src/protocol/event.rs): `src/protocol/event.rs`

### Other components

- **Client application**
- **Server application**
- **Remote process**

## Connections

- Client application → Session manager: requests streams
- Server application → Listener: accepts streams
- Session manager → Connection transport: connects peer
- Connection transport → Remote process: opens connection
- Listener → Connection transport: accepts connection
- Session manager → Session: creates sessions
- Session manager → Session: rebuilds sessions
- Session manager → Stream pool: obtains streams
- Session → Protocol initializer: initializes protocol
- Protocol initializer → Feature negotiation: negotiates V4
- Feature negotiation → V2 / V3 / V4: selects mode
- Protocol initializer → V2 / V3 / V4: handles legacy setup
- Protocol setup → Buffer manager: creates or maps
- Protocol setup → Shared I/O queues: creates or maps
- Protocol initializer → Buffer manager: maps peer memory
- Protocol initializer → Shared I/O queues: maps peer queue
- Session → Shared I/O queues: dispatches queue events
- Session → Wakeup mechanisms: sends and receives wakeups
- Logical stream → Linked buffers: reads and writes
- Linked buffers → Buffer slices: uses slices
- Buffer slices → Buffer manager: allocates and recycles
- Logical stream → Shared I/O queues: enqueues stream data
- Session → Logical stream: routes incoming streams
- Session → Stream pool: reuses streams
- Session → Session statistics: updates counters
- Feature negotiation → Wakeup mechanisms: selects optional mode