Struct shared_buffer::SharedBufferSlice

source ·

pub struct SharedBufferSlice<'a> { /* private fields */ }

Expand description

An immutable slice into a SharedBuffer.

A SharedBufferSlice is created with SharedBuffer::slice, SharedBufferSlice::slice, or SharedBufferSliceMut::slice.

Implementations§

source §

impl<'a> SharedBufferSlice<'a>

source

pub fn read(&self, dst: &mut [u8]) -> usize

Read bytes from the buffer.

Read up to dst.len() bytes from the buffer, returning how many bytes were read. The only thing that can cause fewer bytes to be read than requested is if dst is larger than the buffer itself.

A call to read is only guaranteed to happen after an operation in another thread or process if the mechanism used to signal the other process has well-defined memory ordering semantics. Otherwise, the acquire_writes method must be called before read and after receiving a signal from the other process in order to provide such ordering guarantees. In practice, this means that acquire_writes should be the first read operation that happens after receiving a signal from another process that the memory may be read. See the acquire_writes documentation for more details.

source

pub fn read_at(&self, offset: usize, dst: &mut [u8]) -> usize

Read bytes from the buffer at an offset.

Read up to dst.len() bytes starting at offset into the buffer, returning how many bytes were read. The only thing that can cause fewer bytes to be read than requested is if there are fewer than dst.len() bytes available starting at offset within the buffer.

A call to read_at is only guaranteed to happen after an operation in another thread or process if the mechanism used to signal the other process has well-defined memory ordering semantics. Otherwise, the acquire_writes method must be called before read_at and after receiving a signal from the other process in order to provide such ordering guarantees. In practice, this means that acquire_writes should be the first read operation that happens after receiving a signal from another process that the memory may be read. See the acquire_writes documentation for more details.

§Panics

read_at panics if offset is greater than the length of the buffer.

source

pub fn acquire_writes(&self)

Acquire all writes performed by the other process.

On some systems (such as Fuchsia, currently), the communication mechanism used for signalling a process that memory is readable does not have well-defined synchronization semantics. On those systems, this method MUST be called after receiving such a signal, or else writes performed before that signal are not guaranteed to be observed by this process.

acquire_writes acquires any writes performed on this buffer or any slice within the buffer.

§Note on Fuchsia

Zircon, the Fuchsia kernel, will likely eventually have well-defined semantics around the synchronization behavior of various syscalls. Once that happens, calling this method in Fuchsia programs may become optional. This work is tracked in https://fxbug.dev/42107145.

source

pub fn slice<R: RangeBounds<usize>>(&self, range: R) -> SharedBufferSlice<'a>

Create a sub-slice of this SharedBufferSlice.

Just like the slicing operation on array and slice references, slice constructs a new SharedBufferSlice which points to the same memory as the original, but starting and index from (inclusive) and ending at index to (exclusive).

§Panics

slice panics if range is out of bounds of self or if range is nonsensical (its lower bound is larger than its upper bound).

source

pub fn split_at( &self, idx: usize, ) -> (SharedBufferSlice<'a>, SharedBufferSlice<'a>)

Split this SharedBufferSlice in two.

Just like the split_at method on array and slice references, split_at constructs one SharedBufferSlice which represents bytes [0, idx), and one which represents bytes [idx, len), where len is the length of the buffer slice.