Rust Adapter

Use Zinc from Rust with the zinc-core crate

The Rust adapter is the canonical API. SharedRegion lives in the core crate and exports directly for Rust projects.

Installation

Build the core from a source checkout, then set up the adapter:

cargo add zinc-core --path /path/to/zinc/core

SharedRegion

use zinc_core::{page_size, SharedRegion};

create

Creates a new region. The name must match [a-zA-Z0-9_-]+. The capacity must be a multiple of the system page size (typically 4096).

let region = SharedRegion::create("my-data", page_size())?;

Returns Ok(SharedRegion) on success, or Err(ZincError).

open

Opens an existing region by name. Validates the header magic and version.

let region = SharedRegion::open("my-data")?;

as_ptr

Returns a raw *mut u8 pointing to the data area (first byte after the header page).

let ptr = region.as_ptr();
unsafe { *ptr = 42 };

capacity

Returns the usable size in bytes.

let cap = region.capacity();

notify

Atomically increments the notification sequence counter and wakes all waiters.

region.notify();

wait

Blocks until the notification counter changes, or the timeout expires.

match region.wait(1000) {
    Ok(()) => println!("data available"),
    Err(ZincError::TimedOut) => println!("no update within 1s"),
    Err(e) => eprintln!("error: {e}"),
}

Returns Ok(()) on notification, Err(ZincError::TimedOut) on timeout, or Err(ZincError) for other errors.

try_wait

Consumes a pending notification without blocking. Returns false if the counter has not changed since this handle’s last observation.

if region.try_wait() {
    process_update();
}

Drop

Regions close automatically when SharedRegion drops. If the handle is the creator, the name is unlinked. Openers keep their existing mappings until they close.

{
    let region = SharedRegion::create("temp", 16384)?;
    // region is active here
}
// region is closed and unlinked

Data access

write_at(offset, data), read_at(offset, buf), and write_bytes(offset, value, count) check the entire range before copying or filling bytes. Invalid ranges return ZincError::OutOfBounds without changing either buffer. An empty range at capacity() is valid.

use zinc_core::{page_size, SharedRegion};

let region = SharedRegion::create("checked-data", page_size())?;
let mut result = [0; 4];
// This example has exclusive access to the mapping.
unsafe {
    region.write_at(0, b"ZINC")?;
    region.read_at(0, &mut result)?;
    region.write_bytes(4, 0, 16)?;
}
assert_eq!(&result, b"ZINC");

These methods remain unsafe: prevent concurrent access to bytes being written and concurrent writes to bytes being read. Source and destination buffers must not overlap. Copying bytes does not send a notification; call notify() when the update is ready.

Raw pointers require bounds checks and synchronization by the caller. A successful wait publishes preceding writes but does not keep a producer from overwriting data during a read. See notify and wait for the coordination rules.

Working with the header

RegionHeader is exported for advanced use but you rarely need it. It lives at the base of mapped memory and you can access it with unsafe pointer arithmetic. SharedRegion covers most use cases.

Ring

RingStorage owns an initialized queue of u64 values. Capacity must be a power of two greater than one. RingStorage::default() uses 256 slots.

use zinc_core::ring::RingStorage;

let storage = RingStorage::new(1024)?;
let ring = storage.ring();
assert!(ring.try_push(42));
assert_eq!(ring.pop(), Some(42));
assert!(ring.is_empty());

A ring supports multiple producers and consumers. push returns RingFull when it cannot reserve a slot; try_push returns a boolean. pop returns None when the next slot is not ready. Operations do not park the thread, but reservations can delay later items if a producer is descheduled before publishing.

len, is_empty, and remaining are snapshots. Under contention, len includes reserved slots that have not yet been published. Use push/pop results for flow control.

For shared memory, Ring::from_raw_with_capacity attaches to separately initialized storage. This is unsafe: the caller must provide aligned slots, valid atomic counters, and keep the mapping alive. The header’s ring counters are reserved; SharedRegion does not initialize a ring in its data area.

Run cargo bench -p zinc-core --bench ring to measure push/pop and producer contention. Contention measurements include thread startup for each batch of 4096 values.