Rust API reference

Use the native Rust core directly: send byte slices, receive owned vectors, or reuse your own storage.

Generated crate documentation ↗ · API source ↗

Install

Requires Rust 1.87 or later on a supported little-endian 64-bit platform.

cargo add cloudtoid-interprocess

Send and receive

This complete example keeps both endpoints alive. Separate processes use the same options; on Unix, add .with_path("/absolute/shared/directory") when their temporary directories differ.

use cloudtoid_interprocess::{Options, Publisher, Subscriber};

fn main() -> cloudtoid_interprocess::Result<()> {
    let options = Options::new("example", 65536);
    let subscriber = Subscriber::open(&options)?;
    let publisher = Publisher::open(&options)?;
    publisher.try_send(b"hello")?;
    let message = subscriber.try_recv()?.expect("message is ready");
    assert_eq!(message, b"hello");
    Ok(())
}

Options

Options::new(name: impl Into<String>, capacity: usize) -> Self

Creates configuration using the OS temporary directory. Validation happens when opening an endpoint. Public fields are name: String, path: PathBuf, and capacity: usize. The struct is non-exhaustive; use the constructor rather than a struct literal.

with_path(self, path: impl Into<PathBuf>) -> Self

Sets the Unix backing directory. Windows ignores this option. Capacity is bytes, greater than 16 and divisible by 8; see identity rules.

Publisher

Publisher::open(options: &Options) -> Result<Self>

Creates or joins the queue and registers a publisher. MAX_PUBLISHERS is 2048.

try_send(&self, message: &[u8]) -> Result<()>

Copies a message into the queue without waiting for space. Ok(()) means committed; Error::Full means full or temporarily recovering. Other errors must be handled separately.

try_send_batch(&self, messages: &[&[u8]]) -> Result<usize>

Returns the committed prefix length. A short count, including zero, can indicate full capacity, recovery, or a mid-batch error. Retry only the unsent suffix to observe persistent errors. Errors before any commit are returned immediately. Batches can interleave with other publishers.

Subscriber

Subscriber::open(options: &Options) -> Result<Self>

Creates or joins the queue as a competing subscriber.

try_recv(&self) -> Result<Option<Vec<u8>>>

Copies and consumes one ready message into an owned vector. None means no message is ready; Some(vec![]) is a valid empty message.

try_recv_into(&self, buffer: &mut [u8]) -> Result<Option<usize>>

Copies into your buffer and returns the byte count. Some(0) still means a message was consumed. Oversized messages are truncated and consumed.

recv(&self) -> Result<Vec<u8>>

Blocks the calling thread until a message is received or an error occurs.

recv_timeout(&self, timeout: Duration) -> Result<Option<Vec<u8>>>

Blocks for up to the timeout, subject to scheduling and operation overhead. None means timeout. A zero duration attempts once. Received vectors belong to the caller.

Errors

Result<T> aliases std::result::Result<T, Error>. Error is non-exhaustive and implements Display and std::error::Error. Use error.is_full() for retryable admission failures.

Full

No space or recovery admission unavailable.

Invalid(&'static str)

Invalid options or message length.

CapacityMismatch

Existing queue capacity differs.

PublisherLimit

All publisher registrations are occupied.

Exhausted

A lifetime counter cannot advance; use a fresh queue.

Corrupt

Invalid shared queue state.

Io(std::io::Error)

An OS operation failed; available through the error source.

Waiting and cleanup

Endpoints release registrations on Drop. Keep at least one endpoint alive to retain the queue. Open endpoints after fork(). Blocking receives have no async-runtime integration: use a blocking worker with bounded timeouts if you need controlled shutdown from an async application. Aborting an async task does not cancel a Rust blocking receive already running on a worker.