# ipc-ring48
`ipc-ring48` is a Rust shared-memory IPC primitive for passing fixed 48-byte messages through a bounded one-producer/one-consumer queue.
The core primitive is exposed as a library and also provided through a CLI.
The design is local and exact:
* one producer,
* one consumer,
* fixed 48-byte messages,
* bounded power-of-two capacity,
* POSIX shared memory,
* cacheline-aligned ABI,
* non-blocking push,
* non-blocking pop,
* no allocation in the hot path,
* reusable Rust API,
* convenient CLI views,
* portable static musl builds.
## Purpose
One producer appends compact binary messages into a shared queue.
One consumer removes messages in FIFO order.
The queue stores each message as exactly 48 bytes.
## Version
```text
ipc-ring48 v1.0.1
```
## Quick Start
Build the portable static release binary:
```bash
rustup target add x86_64-unknown-linux-musl
cargo build --release
```
Initialise a queue with 1024 slots:
```bash
target/x86_64-unknown-linux-musl/release/ipc-ring48 unlink || true
target/x86_64-unknown-linux-musl/release/ipc-ring48 init 1024
```
Push and pop six `u64` values:
```bash
target/x86_64-unknown-linux-musl/release/ipc-ring48 push-u64 1 7 13 43 127 255
target/x86_64-unknown-linux-musl/release/ipc-ring48 pop-u64
```
Expected output:
```text
1 7 13 43 127 255
```
Roundtrip a 48-byte binary message:
```bash
head -c 48 /dev/urandom > state.bin
target/x86_64-unknown-linux-musl/release/ipc-ring48 push-file state.bin
target/x86_64-unknown-linux-musl/release/ipc-ring48 pop-bin > copy.bin
cmp state.bin copy.bin
rm -f state.bin copy.bin
```
## Public Documents
* [CHEAT_SHEET.md](CHEAT_SHEET.md) — concise command and API reference.
* [BENCHMARKING.md](BENCHMARKING.md) — benchmark commands, system context, and readings.
* [LICENSE.md](LICENSE.md) — The Kindness Licence.
* [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — dependency licence attribution.
## Platform
This implementation targets Linux and uses POSIX shared memory through `libc`.
The shared memory object name is:
```text
/ipc_ring48_queue
```
## CLI
```text
ipc-ring48 init <capacity>
ipc-ring48 push-text <value>
ipc-ring48 push <value>
ipc-ring48 push-file <path>
ipc-ring48 push-stdin
ipc-ring48 push-hex <96 hex chars>
ipc-ring48 push-u64 <a> <b> <c> <d> <e> <f>
ipc-ring48 pop
ipc-ring48 pop-text
ipc-ring48 pop-hex
ipc-ring48 pop-bin
ipc-ring48 pop-u64
ipc-ring48 stats
ipc-ring48 unlink
```
`push` and `push-text` are aliases.
When the queue is full, push commands print `queue full` and exit with code `2`.
When the queue is empty, pop commands print `queue empty` and exit with code `2`.
## Library Usage
Add the crate:
```toml
[dependencies]
ipc-ring48 = "1.0.1"
```
Producer:
```rust
use ipc_ring48::Producer;
fn main() -> std::io::Result<()> {
let producer = Producer::create_or_open(1024)?;
producer.push([1_u8; 48]).expect("queue has space");
Ok(())
}
```
Consumer:
```rust
use ipc_ring48::Consumer;
fn main() -> std::io::Result<()> {
let consumer = Consumer::open()?;
if let Some(message) = consumer.pop() {
println!("received {} bytes", message.len());
}
Ok(())
}
```
Cleanup:
```rust
fn main() -> std::io::Result<()> {
ipc_ring48::unlink()
}
```
## ABI
The shared region contains:
```text
SharedHeader #[repr(C, align(64))]
Producer counter #[repr(C, align(64))]
Consumer counter #[repr(C, align(64))]
Slot array #[repr(C, align(64))]
```
Each slot contains:
```text
payload: [u8; 48]
reserved: [u8; 16]
```
The slot size is 64 bytes.
Queue state is tracked by two monotonic counters:
```text
head = producer-owned counter
tail = consumer-owned counter
```
Full condition:
```text
head - tail == capacity
```
Empty condition:
```text
head == tail
```
Slot index:
```text
counter & (capacity - 1)
```
## Build Verification
```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
cargo doc --no-deps
cargo package
cargo publish --dry-run
```
Confirm the static musl binary:
```bash
ls -lh target/x86_64-unknown-linux-musl/release/ipc-ring48
file target/x86_64-unknown-linux-musl/release/ipc-ring48
```
## Benchmarking
Run library benchmarks:
```bash
cargo bench --bench ipc_ring48
```
Run CLI benchmarks:
```bash
./scripts/bench_cli.sh target/x86_64-unknown-linux-musl/release/ipc-ring48 1000
```
Record readings in [BENCHMARKING.md](BENCHMARKING.md).
## Release State
```text
ipc-ring48 v1.0.1
```
The `v1.0.1` release is sealed, tagged, published, benchmarked, and documented.
The crate is available on crates.io:
```toml
[dependencies]
ipc-ring48 = "1.0.1"
```