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

ipc-ring48 v1.0.1

Quick Start

Build the portable static release binary:

rustup target add x86_64-unknown-linux-musl
cargo build --release

Initialise a queue with 1024 slots:

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:

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:

1 7 13 43 127 255

Roundtrip a 48-byte binary message:

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 — concise command and API reference.
• BENCHMARKING.md — benchmark commands, system context, and readings.
• LICENSE.md — The Kindness Licence.
• 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:

/ipc_ring48_queue

CLI

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:

[dependencies]
ipc-ring48 = "1.0.1"

Producer:

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:

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:

fn main() -> std::io::Result<()> {
    ipc_ring48::unlink()
}

ABI

The shared region contains:

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:

payload: [u8; 48]
reserved: [u8; 16]

The slot size is 64 bytes.

Queue state is tracked by two monotonic counters:

head = producer-owned counter
tail = consumer-owned counter

Full condition:

head - tail == capacity

Empty condition:

head == tail

Slot index:

counter & (capacity - 1)

Build Verification

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:

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:

cargo bench --bench ipc_ring48

Run CLI benchmarks:

./scripts/bench_cli.sh target/x86_64-unknown-linux-musl/release/ipc-ring48 1000

Record readings in BENCHMARKING.md.

Release State

ipc-ring48 v1.0.1

The v1.0.1 release is sealed, tagged, published, benchmarked, and documented.

The crate is available on crates.io:

[dependencies]
ipc-ring48 = "1.0.1"