Struct redox_buffer_pool::BufferSlice

pub struct BufferSlice<'pool, I, H, E, G = NoGuard, C = BufferPool<I, H, E>, M: Mode = Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>,  { /* fields omitted */ }

A slice from the buffer pool, that can be read from or written to as a regular smart pointer.

The buffer slice struct has one lifetime argument, 'pool, which is only used if the buffer slice references the pool directly using a regular reference, which is the case for acquire_borrowed_slice. For slices allocated with acquire_strong_slice and acquire_weak_slice, this lifetime will be 'static.

Of the five generic type arguments, I, H, and E, are more or less inherited from the buffer pool; while only I (for numbers) and E (for the extra field) are used, they are needed since the buffer pool itself also has to be involved for some operations. The G parameter, is the guard type, which defaults to no guard at all, but allows the memory of the buffer slice to stay protected and leak the memory if the guard couldn't free it. The C parameter is meant for wrappers structs over BufferPool, to allow std::sync::Arcs or std::sync::Weaks pointing to them instead.

The M generic parameter is used for the "guarding mode", an must implement the guard_trait::marker::Mode trait. It has no effect whatsoever on the data, but controls what can and what cannot be done in safe code, with respect to the guard. The exclusive mode will limit the ability to access the memory mutably or immutably, while the guard is present, while the shared mode will only forbid mutable access, while the guard is active, but always allow immutable access. Buffer slices can be converted to and from these types, though converting from shared into exclusive requires proof that there is no aliasing going on.

Implementations

impl<'pool, I, H, E, G, C, M> BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>,
    M: Mode, 

pub fn pool_is_alive(&self) -> bool

Checks whether the pool that owns this slice is still alive, or if it has dropped. Note that this only makes sense for weak buffer slices, since buffer slices tied to a lifetime cannot outlive their pools (checked for at compile time), while strong buffer slices ensure at runtime that they outlive their pools.

For weak buffer slices, this method should be called before doing anything with the slice, since a single deref could make it panic if the buffer isn't there anymore.

pub unsafe fn as_slice_unchecked(&self) -> &[u8]

Constructs an immutable slice from this buffer, provided that there is no guard protecting the memory

Panics

This method uses debug assertions to verify that the pool has not been dropped, and that there is no guard in case M is Exclusive.

Safety

For this to be safe, the caller must ensure that the pool has not been dropped (which is only possible when weakly referenced), and that there is no existing guard while M is Exclusive.

pub fn try_as_slice(&self) -> Option<&[u8]>

Tries to construct an immutable slice from this buffer, returning None if the pool has been dropped (and hence, this is a weak slice), or if there is a guard and the mode is exclusive.

pub unsafe fn as_slice_mut_unchecked(&mut self) -> &mut [u8]

Construct a mutable slice from this buffer.

Panics

This method uses debug assertions to verify that the pool is alive, and that a guard is not present.

Safety

For this to be safe, the caller must ensure that the pool has not been dropped (which is only possible when weakly referenced), and that there is no existing guard at all.

pub fn try_as_slice_mut(&mut self) -> Option<&mut [u8]>

Tries to construct a mutable slice from this buffer, returning None if the pool has been destroyed, or if there is an existing guard.

pub unsafe fn unguard_unchecked(&mut self) -> Option<G>

Forcefully remove a guard from a future, from this slice, returning it if there was a guard already.

Safety

This is unsafe because it allows removing guards set by pending futures; although this is completely fine when there are no pending ones, the buffer slice will be reclaimed without the guard, causing UB if any producer keeps using its pointer. Also, exclusive slices may be able to mutably alias if code relies on that being upheld.

pub fn guard(&mut self, guard: G) -> Result<(), WithGuardError<G>>

Adds a guard to this buffer, preventing it from deallocating unless the guard accepts that. This is crucial when memory is shared with another component that may be outside this process's address space. If there is a pending io_uring submission or a pending NVME command for instance, this guard will fail if the buffer is in use by a command, and leak the memory instead when dropping.

This will error with WithGuardError if there is already an active guard.

pub fn with_guard<OtherGuard: Guard>(
    self,
    other: OtherGuard
) -> WithGuardResult<'pool, I, H, E, G, OtherGuard, C, M>

Tries to add a guard of potentially a different type than the guard type in this slice. Because of that this, this will consume self and construct a different BufferSlice with a different guard type, or error with self if there was already a guard present.

pub fn reclaim(self) -> Result<(), ReclaimError<Self>>

Reclaim the buffer slice, equivalent to dropping but with a Result. If the buffer slice was guarded by a future, this will fail with ReclaimError if the future hadn't completed when this was called.

pub fn offset(&self) -> I

Get the offset of the buffer pool where this was allocated.

pub fn len(&self) -> I

Get the length of the allocation slice.

pub fn capacity(&self) -> I

Get the capacity of the allocation slice. This is almost always the same as the length, but may be larger in case the allocator chose a larger size to align the range afterwards.

pub fn is_empty(&self) -> bool

Check whether the slice is empty or not.

pub fn mmap_offset(&self) -> I

Get the offset of the underlying possibly non-continuously-organized mmap, that was added as part of BufferPool::begin_expand.

pub fn mmap_size(&self) -> I

Get the size of the mmap region this slice was allocated in.

pub fn extra(&self) -> E

Get the extra field from the mmap region this slice belongs to, copied.

pub fn has_guard(&self) -> bool

Check whether there exists a guard protecting the memory.

impl<'pool, I, H, E, G, C> BufferSlice<'pool, I, H, E, G, C, Shared> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

pub fn as_slice(&self) -> &[u8]

Get a slice from the buffer chunk.

impl<'pool, I, H, E, C> BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

pub fn as_slice(&self) -> &[u8]

Get a slice from the buffer chunk, provided that the cannot exist any guard.

pub fn as_slice_mut(&mut self) -> &mut [u8]

Get a mutable slice from from the buffer chunk. This requires that there cannot be any guard; otherwise, use try_as_slice_mut.

Trait Implementations

impl<'pool, I, H, E, C> AsMut<[u8]> for BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

fn as_mut(&mut self) -> &mut [u8]

Performs the conversion.

impl<'pool, I, H, E, G, C> AsRef<[u8]> for BufferSlice<'pool, I, H, E, G, C, Shared> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl<'pool, I, H, E, C> AsRef<[u8]> for BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl<'pool, I, H, E, G, C> Borrow<[u8]> for BufferSlice<'pool, I, H, E, G, C, Shared> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

fn borrow(&self) -> &[u8]

Immutably borrows from an owned value.

impl<'pool, I, H, E, C> Borrow<[u8]> for BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

fn borrow(&self) -> &[u8]

Immutably borrows from an owned value.

impl<'pool, I, H, E, C> BorrowMut<[u8]> for BufferSlice<'pool, I, H, E, NoGuard, C> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

fn borrow_mut(&mut self) -> &mut [u8]

Mutably borrows from an owned value.

impl<'pool, I: Debug, H: Debug, E: Debug, G: Debug, C: Debug, M: Debug + Mode> Debug for BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

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

Formats the value using the given formatter.

impl<'pool, I, H, E, G, C> Deref for BufferSlice<'pool, I, H, E, G, C, Shared> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

type Target = [u8]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'pool, I, H, E, C> Deref for BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

type Target = [u8]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'pool, I, H, E, C> DerefMut for BufferSlice<'pool, I, H, E, NoGuard, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    C: AsBufferPool<I, H, E>, 

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'pool, I, H, E, G, C, M> Drop for BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    G: Guard,
    E: Copy,
    H: Handle<I, E>,
    C: AsBufferPool<I, H, E>,
    M: Mode, 

fn drop(&mut self)

Executes the destructor for this type.

impl<'pool, I, E, G, H, C, M> Guardable<G, [u8]> for BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>,
    M: Mode, 

fn try_guard(&mut self, guard: G) -> Result<(), G>

Attempt to insert a guard into the guardable, if there was not already a guard inserted. If that were the case, error with the guard that was not able to be inserted.

fn try_get_data(&self) -> Option<&[u8]>

Try to retrieve the inner data immutably, unless there is a guard.

impl<'pool, I, E, G, H, C> GuardableExclusive<G, [u8]> for BufferSlice<'pool, I, H, E, G, C, Exclusive> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

fn try_get_data_mut(&mut self) -> Option<&mut [u8]>

Attempt to retrieve the inner mutable data, so long as there is not a guard.

impl<'pool, I, E, G, H, C> GuardableShared<G, [u8]> for BufferSlice<'pool, I, H, E, G, C, Shared> where
    I: Integer,
    H: Handle<I, E>,
    E: Copy,
    G: Guard,
    C: AsBufferPool<I, H, E>, 

fn data_shared(&self) -> &[u8]

Retrieve the inner aliasable data that this guardable points to.

impl<'pool, I, H, E, G, C, M> Send for BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    H: Handle<I, E> + Send + Sync,
    E: Copy + Send,
    G: Guard + Send,
    C: AsBufferPool<I, H, E>,
    M: Mode, 

impl<'pool, I, H, E, G, C, M> Sync for BufferSlice<'pool, I, H, E, G, C, M> where
    I: Integer,
    H: Send + Sync + Handle<I, E>,
    E: Copy + Sync,
    G: Sync + Guard,
    C: AsBufferPool<I, H, E>,
    M: Mode,