Crate xchannel 

xchannel: mmap-backed IPC channels with rolling files.

Overview

• Regionized file layout; region 0 starts with a MessageHeader(Channel) followed by ChannelHeader.
• Pre-header pipeline for user records: For record i: header(i) is pre-installed (committed=0) at the end of try_reserve(i-1) (and the very first one at file create time). try_reserve(i) then pre-installs header(i+1) before returning the buffer for slot i. The caller fills the payload and calls commit, which fills header(i) and release-stores committed=1. At any point a reader observes committed[i] = 1 with acquire semantics, slot i+1 is guaranteed to bear the pre-install signature.
• Special markers: Skip (pad to next region), Roll (file rolled).

Safety

Writers produce &mut references into an mmap; do not run a reader in the same process concurrently with a writer to the same file/region. For cross-process IPC this is fine. Publishing uses Release and reading uses Acquire.

Structs

GenerationMismatch

The channel at a reader’s path is not the incarnation the caller expected.

Helper

Where a writer’s or reader’s helper thread runs.

IndexPruned

The requested record index is older than anything still on disk: retention (keep_files) has removed the segment that held it.

MessageBatch

Borrowed view over a batch of user messages.

MessageRef

Borrowed view of a message payload and header.

OwnedMessage

An owned message: a share of the mapped region plus the record’s position within it. Carries no lifetime, so it can be stored, collected into a Vec, or sent to another thread.

PeekedHeader

What the next user record says about itself, read without consuming it.

Reader

ReaderBuilder

RegionMapping

Encapsulates a single mmap-ed region. Mode is Mmap (read-only) or MmapMut (writable).

Writer

WriterBuilder

Enums

ReaderMode

Where a new Reader starts. Non-exhaustive: further modes may be added without a major version, so a match on it needs a wildcard arm.

Unmap

When a writer or reader releases the regions it has moved past.

Constants

CHANNEL_NAME_MAX

Maximum bytes available for a channel name in ChannelHeader.

Functions

cleanup_channel_files

Remove channel base and all rolled files created by this crate. Scans the parent directory for entries matching base and base.<N> and removes them, so this works correctly even when retention has left a sparse set of rolled files (e.g. with WriterBuilder::keep_files).

page_size

Return the OS page size.

wait_any

Block until any of readers has a user message at its cursor, and return its index; or return Ok(None) once the optional timeout has passed. timeout = None waits indefinitely.

Type Aliases

ReadOnly

Writable