Struct Publisher

Source

pub struct Publisher { /* private fields */ }

Expand description

O(1) zero-copy publisher over shared memory.

Uses a shared block pool (Treiber stack) for data storage and a ring of block indices for publication. Transfer cost is O(1) regardless of payload size – only 8 bytes (block index + data length) are written to the ring.

§Examples

use crossbar::*;

let mut pub_ = Publisher::create("prices", Config::default()).unwrap();
let topic = pub_.register("/tick/AAPL").unwrap();

let mut loan = pub_.loan(&topic).unwrap();
loan.as_mut_slice()[..8].copy_from_slice(&42u64.to_le_bytes());
loan.set_len(8).unwrap();
loan.publish(); // O(1) -- writes 8 bytes to ring

Implementations§

Source §

impl Publisher

Source

pub fn create(name: &str, config: Config) -> Result<Self, Error>

Creates a new pool-backed pub/sub region.

§Errors

Returns Error::Io if the backing file cannot be created, or Error::InvalidRegion if another publisher is active.

Source

pub fn open(name: &str) -> Result<Self, Error>

Opens an existing pub/sub region as a secondary publisher.

Unlike create, this does not create the SHM file or hold an exclusive lock. The region must already exist (created by another Publisher::create call). Config is read from the header.

§Errors

Returns an error if the region file doesn’t exist, has invalid magic/version, or the publisher’s heartbeat is stale.

Source

pub fn register(&mut self, uri: &str) -> Result<Topic, Error>

Registers a topic URI (untyped). Returns a handle for use with loan.

§Errors

Returns an error if the maximum number of topics has been reached or the URI exceeds 64 bytes.

Source

pub fn register_typed<T: Pod>(&mut self, uri: &str) -> Result<Topic, Error>

Registers a typed topic URI. Returns a handle for use with loan_typed.

The type size is stored in the topic entry so that subscribers can verify the expected type size at receive time.

§Errors

Returns an error if T’s alignment exceeds 8, the maximum number of topics has been reached, or the URI exceeds 64 bytes.

Source

pub fn heartbeat(&mut self) -> Result<(), Error>

Updates the publisher heartbeat. Call this periodically during idle periods (when not calling loan) to prevent subscribers from treating the publisher as dead.

loan() updates the heartbeat automatically every 1024 calls, so you only need this if the publisher may be idle longer than stale_timeout. Updates the publisher heartbeat.

§Errors

Returns Error::ClockError if the system clock is before UNIX epoch.

Source

pub fn loan(&mut self, handle: &Topic) -> Result<Loan<'_>, Error>

Loans a block from the pool for writing. Write your data, then call publish to make it visible to subscribers.

If the loan is dropped without publishing, the block is returned to the pool automatically.

§Errors

Returns Error::PoolExhausted if all blocks are in use.

Source

pub fn loan_typed<T: Pod>( &mut self, handle: &Topic, ) -> Result<TypedLoan<'_, T>, Error>

Loans a typed block from the pool for writing a T: Pod value.

Use TypedLoan::send to write and publish in one step, or TypedLoan::as_mut + TypedLoan::publish to fill fields individually (born-in-SHM pattern).

§Errors

Returns Error::PoolExhausted if all blocks are in use.

Source

pub fn loan_pinned(&mut self, handle: &Topic) -> Result<PinnedLoan<'_>, Error>

Loans the pinned block for a topic. On the first call, allocates a dedicated block. Subsequent calls return the same block – no alloc.

The publisher uses a CAS-based writer sentinel to prevent data races: if any subscriber holds a PinnedGuard for this topic, this method returns an error.

§Errors

Error::PinnedReadersActive if a subscriber holds a PinnedGuard.
Error::PoolExhausted if the pool is exhausted (first call only).

Source

pub fn subscriber_count(&self, handle: &Topic) -> Result<u32, Error>

Returns the number of active subscribers for a topic.

This is an informational counter stored in shared memory. It is incremented when a Stream is created and decremented when the subscription is dropped.