Struct shared_buffer::SharedBufferSliceMut

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

A mutable slice into a SharedBuffer.

A SharedBufferSliceMut is created with SharedBuffer::slice_mut or SharedBufferSliceMut::slice_mut.

Implementations

impl<'a> SharedBufferSliceMut<'a>

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.

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.

pub fn write(&self, src: &[u8]) -> usize

Write bytes to the buffer.

Write up to src.len() bytes into the buffer, returning how many bytes were written. The only thing that can cause fewer bytes to be written than requested is if src is larger than the buffer itself.

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

pub fn write_at(&self, offset: usize, src: &[u8]) -> usize

Write bytes to the buffer at an offset.

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

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

Panics

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

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.

pub fn release_writes(&mut self)

Atomically release all writes performed so far.

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

release_writes releases any writes performed on this slice or any sub-slice of this slice.

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.

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

Create a sub-slice of this SharedBufferSliceMut.

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).

pub fn slice_mut<R: RangeBounds<usize>>( &mut self, range: R ) -> SharedBufferSliceMut<'a>

Create a mutable slice of the original SharedBufferSliceMut.

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

Panics

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

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

Split this SharedBufferSliceMut into two immutable slices.

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.

Panics

split_at panics if idx > self.len().

pub fn split_at_mut( &mut self, idx: usize ) -> (SharedBufferSliceMut<'a>, SharedBufferSliceMut<'a>)

Split this SharedBufferSliceMut in two.

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

Panics

split_at_mut panics if idx > self.len().

pub fn len(&self) -> usize

The number of bytes in this SharedBufferSlice.

Trait Implementations

impl<'a> Debug for SharedBufferSliceMut<'a>

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

Formats the value using the given formatter.

impl<'a> Send for SharedBufferSliceMut<'a>

impl<'a> Sync for SharedBufferSliceMut<'a>