Struct ByteQueue

pub struct ByteQueue { /* private fields */ }

The main queue type. Read the crate documentation for further information and usage examples.

Implementations

impl ByteQueue

pub unsafe fn create(mem: *mut u8, mem_len: usize) -> Self

Creates a new queue in the given memory region and initializes both pointers.

Safety

This method has to be called before the other processor tries to access the queue because the other processor might access an uninitialized memory region otherwise which will most likely result in crashes.

Obviously, the memory pointer and the memory region length must be correct, reserved for this purpose and known to the other processor.

pub unsafe fn attach(mem: *mut u8, mem_len: usize) -> Self

Attaches to a queue which has previously been initialized by ByteQueue::create, possibly by an other processor.

Safety

This method must not be called before the other processor has properly initialized the queue because this will most likely result in crashes.

Obviously, the memory pointer rand the memory region length must be correct, reserved for this purpose and known to the other processor.

pub fn space(&self) -> usize

Returns the size of the available space, which can be written into the queue.

pub fn size(&self) -> usize

Returns the size of the written messages, which are to be consumed or read.

pub fn nb_write(&mut self, data: &[u8]) -> Result<(), Infallible>

Attempts to write data to the queue in non-blocking mode.

If there is not enough space to write the entire data, returns an error (WouldBlock). On success, writes the data into the queue, using memory fences for proper synchronization.

pub fn blocking_write(&mut self, data: &[u8])

Blocks until there is enough space in the queue to write the data.

Once space is available, writes the data to the queue using nb_write.

pub fn nb_read(&mut self, buf: &mut [u8]) -> Result<(), Infallible>

Attempts to read data from the queue in non-blocking mode.

If there is not enough data in buf.len() size available to be read, returns an error (WouldBlock). On success, reads the data in buf.len() size from the queue into the provided buffer, using memory fences for synchronization.

pub fn consume_at_most(&mut self, buf: &mut [u8]) -> usize

Reads up to the available data into the provided buffer, returning the number of bytes read.

This method reads at most the size of the buffer or the amount of available data, whichever is smaller.

pub fn blocking_read(&mut self, buf: &mut [u8])

Blocks until there is enough data in the queue to fill the buffer.

Once sufficient data is available, reads the data using nb_read.

Trait Implementations

impl Debug for ByteQueue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Write for ByteQueue

fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl Send for ByteQueue

The ByteQueue is not automatically Send because it contains raw pointers. According to the Nomicon, raw pointers could be considered “fine […] to be marked as thread safe” but their “non-trivial untracked ownership” requires to decide manually if a type containing raw pointers is Send.

Regarding the ByteQueue, every instantiation and usage is so unsafe that the user needs to be careful anyway. If all usage requirements are still met, the ByteQueue can safely be used from another thread, too. Therefore, Send is implemented manually here to increase the flexibility for the users.

An other perspective on implementing Send is that the ByteQueue is fundamentally designed to be used for inter-processor communication which is in many ways equivalent to inter-thread operation. Thus, implementing Send does not introduce any new requirements.