# bloomdb-labs/buffer_ring architecture

> Architecture diagram of the GitHub repository bloomdb-labs/buffer_ring, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bloomdb-labs/buffer_ring
- Repository: https://github.com/bloomdb-labs/buffer_ring

## Overview

Buffer Ring is a Rust library that stages concurrent writes in aligned buffers and dispatches sealed buffers to storage through io_uring. The principal workflow is caller → ring reservation and buffer write → sealing/rotation → optional flush → asynchronous completion and buffer reuse. Manual flushing, completion notifications, and parallel or serialized write modes are additional capabilities. The graph follows README statements and shown excerpts; some implementation details, especially unsampled code, are not inferred.

Main entry points: [`src/ring.rs`](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs) (Buffer Ring), [`src/flush_buffer.rs`](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/flush_buffer.rs) (Flush Buffer), [`src/quik_io.rs`](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/quik_io.rs) (QuikIO Modes), [`src/lib.rs`](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/lib.rs) (Aligned Buffer Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_staging["Write Staging"]
  node_ring["Buffer Ring<br/>[ring.rs]"]
  node_buffer["Flush Buffer<br/>[flush_buffer.rs]"]
  node_memory["Aligned Buffer Memory<br/>[lib.rs]"]
  node_state["Packed Atomic State<br/>[state.rs]"]
  node_rotation["Rotation and Addressing<br/>[ring.rs]"]
end

subgraph group_dispatch["I/O Dispatch"]
  node_flush["Flush Dispatch<br/>[ring.rs]"]
  node_quikio["QuikIO Modes<br/>[quik_io.rs]"]
  node_uring["io_uring"]
  node_storage[("Backing File")]
end

subgraph group_completion["Completion"]
  node_cq["Completion Handling<br/>[ring.rs]"]
  node_notifier["Completion Receiver<br/>[ring.rs]"]
end

node_caller(("Storage Client"))

node_caller -->|"writes through"| node_ring
node_ring -->|"reserves and writes"| node_buffer
node_buffer -->|"stores payload"| node_memory
node_buffer -->|"updates atomically"| node_state
node_ring -->|"seals and rotates"| node_rotation
node_ring -->|"flushes when enabled"| node_flush
node_caller -->|"may flush manually"| node_flush
node_flush -->|"dispatches buffer"| node_quikio
node_quikio -->|"submits writes"| node_uring
node_uring -->|"writes asynchronously"| node_storage
node_quikio -->|"reads and syncs"| node_storage
node_ring -->|"checks completions"| node_cq
node_cq -->|"retries failed writes"| node_quikio
node_cq -->|"resets on success"| node_buffer
node_cq -->|"sends written ranges"| node_notifier

click node_ring "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs"
click node_buffer "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/flush_buffer.rs"
click node_memory "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/lib.rs"
click node_state "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/state.rs"
click node_rotation "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs"
click node_flush "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs"
click node_quikio "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/quik_io.rs"
click node_cq "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs"
click node_notifier "https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.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_ring,node_buffer,node_memory,node_state,node_rotation toneBlue
class node_flush,node_quikio,node_uring,node_storage,node_caller toneAmber
class node_cq,node_notifier toneMint
```

## Components

### Write Staging

- [Buffer Ring](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs): `src/ring.rs`
- [Flush Buffer](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/flush_buffer.rs): `src/flush_buffer.rs`
- [Aligned Buffer Memory](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/lib.rs): `src/lib.rs`
- [Packed Atomic State](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/state.rs): `src/state.rs`
- [Rotation and Addressing](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs): `src/ring.rs`

### I/O Dispatch

- [Flush Dispatch](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs): `src/ring.rs`
- [QuikIO Modes](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/quik_io.rs): `src/quik_io.rs`
- **io_uring**
- **Backing File**

### Completion

- [Completion Handling](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs): `src/ring.rs`
- [Completion Receiver](https://github.com/bloomdb-labs/buffer_ring/blob/master/src/ring.rs): `src/ring.rs`

### Other components

- **Storage Client**

## Connections

- Storage Client → Buffer Ring: writes through (evidence: `README.md`)
- Buffer Ring → Flush Buffer: reserves and writes (evidence: `src/ring.rs`)
- Flush Buffer → Aligned Buffer Memory: stores payload (evidence: `src/flush_buffer.rs`)
- Flush Buffer → Packed Atomic State: updates atomically (evidence: `src/flush_buffer.rs`)
- Buffer Ring → Rotation and Addressing: seals and rotates (evidence: `src/ring.rs`)
- Buffer Ring → Flush Dispatch: flushes when enabled (evidence: `src/ring.rs`)
- Storage Client → Flush Dispatch: may flush manually (evidence: `README.md`)
- Flush Dispatch → QuikIO Modes: dispatches buffer (evidence: `src/ring.rs`)
- QuikIO Modes → io_uring: submits writes (evidence: `src/quik_io.rs`)
- io_uring → Backing File: writes asynchronously (evidence: `README.md`)
- QuikIO Modes → Backing File: reads and syncs (evidence: `src/quik_io.rs`)
- Buffer Ring → Completion Handling: checks completions (evidence: `src/ring.rs`)
- Completion Handling → QuikIO Modes: retries failed writes (evidence: `src/ring.rs`)
- Completion Handling → Flush Buffer: resets on success (evidence: `src/ring.rs`)
- Completion Handling → Completion Receiver: sends written ranges (evidence: `src/ring.rs`)
