Struct ByteQueue

pub struct ByteQueue { /* private fields */ }

The ByteQueue queue type. Read the crate and module 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 capacity(&self) -> usize

pub fn size(&self) -> usize

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

pub fn write_at_most(&mut self, data: &[u8]) -> usize

Writes at most len bytes into the byte queue, or less depending on the given size of the data to be written, and the currently available space in the byte queue.

Memory fences are used for proper synchronization.

pub fn write_or_fail(&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.

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

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

Once space is available, writes data.len() bytes of data to the queue.

pub fn skip_at_most(&mut self, len: usize) -> usize

Skips at most len bytes, or less depending on the size of the written data in the byte queue.

pub fn skip_or_fail(&mut self, len: usize) -> Result<(), Infallible>

Attempts to skip len bytes in non-blocking mode.

If there is not enough data to be skipped, returns an error (WouldBlock). On success, skips len bytes of written data.

pub fn skip_blocking(&mut self, len: usize)

Blocks until there is enough data in the queue to be skipped.

Once enough data is available, skips len bytes of data in the queue.

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

Read at most len bytes without losing them in the queue, or less depending on the size of the written data in the byte queue.

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

Attempts to fill the buffer completely with the data in the byte queue in non-blocking mode.

If there is not enough data, returns an error (WouldBlock). On success, read buf.len() bytes of written data without skipping them in the byte queue.

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

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

On success, read buf.len() bytes of written data without skipping them in the byte queue.

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/consumes at most the size of the buffer or the amount of available data, whichever is smaller.

pub fn consume_or_fail(&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/consumes the data in buf.len() size from the queue into the provided buffer.

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

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

On success, reads/consumes the data in buf.len() size from the queue into the provided buffer.

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.