Struct SelfContainedChannel

#[repr(C)]
pub struct SelfContainedChannel<T> { /* private fields */ }

A fairly minimal channel implementation that implements the vasi::VirtualAddressSpaceIndependent trait.

Breaking the documented API contracts may result both in immediate panics, and panics in subsequent operations on the channel. To avoid this, the user must:

• Never allow parallel send or receive operations. This is a single-producer, single-consumer channel.
• Never call send when there is already a message pending.

Loosely inspired by the channel implementation examples in “Rust Atomics and Locks” by Mara Box (O’Reilly). Copyright 2023 Mara Box, 978-1-098-11944-7. (From the preface: “You may use all example code offered with this book for any purpose”).

TODO: Several candidate optimizations have been evaluated and discarded, but are left in the commit history for posterity along with their corresponding microbenchmark results.

One that might be worth revisiting is to remove the internal “Reading” and “Writing” states and either make the interfaces unsafe (since it becomes the caller’s responsibility to avoid parallel reads or writes), or add checked creation of !Sync Reader and Writer objects. This optimization appeared to have a 22% benefit in the “ping pong” microbenchmark on a large simulation machine, but only a 3.5% benefit in the “ping pong pinned” microbenchmark; the latter is expected to be more representative of real large simulation runs (i.e. pinning should be enabled).

Implementations

impl<T> SelfContainedChannel<T>

pub fn new() -> Self

pub fn send(&self, message: T)

Sends message through the channel.

Panics if the channel already has an unreceived message.

pub fn receive(&self) -> Result<T, SelfContainedChannelError>

Blocks until either the channel contains a message, or the writer has closed the channel.

Returns Ok(T) if a message was received, or Err(SelfContainedMutexError::WriterIsClosed) if the writer is closed.

Panics if another thread is already trying to receive on this channel.

pub fn close_writer(&self)

Closes the “write” end of the channel. This will cause any current and subsequent receive operations to fail once the channel is empty.

This method can be called in parallel with other methods on the channel, making it suitable to be called from a separate watchdog thread that detects that the writing thread (or process) has died.

pub fn writer_is_closed(&self) -> bool

Whether the write-end of the channel has been closed (via close_writer).

Trait Implementations

impl<T> Default for SelfContainedChannel<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for SelfContainedChannel<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: VirtualAddressSpaceIndependent> VirtualAddressSpaceIndependent for SelfContainedChannel<T>

const IGNORE: () = _

Used by the derive macro to validate that fields are Vasi.

impl<T> Send for SelfContainedChannel<T>

where T: Send,

impl<T> Sync for SelfContainedChannel<T>

where T: Send,