[−][src]Struct redox_buffer_pool::BufferSlice
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::Arc
s or
std::sync::Weak
s 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,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
M: Mode,
pub fn pool_is_alive(&self) -> bool
[src]
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]
[src]
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]>
[src]
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]
[src]
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]>
[src]
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>
[src]
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>>
[src]
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>
[src]
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>>
[src]
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
[src]
Get the offset of the buffer pool where this was allocated.
pub fn len(&self) -> I
[src]
Get the length of the allocation slice.
pub fn capacity(&self) -> I
[src]
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
[src]
Check whether the slice is empty or not.
pub fn mmap_offset(&self) -> I
[src]
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
[src]
Get the size of the mmap region this slice was allocated in.
pub fn extra(&self) -> E
[src]
Get the extra field from the mmap region this slice belongs to, copied.
pub fn has_guard(&self) -> bool
[src]
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
pub fn as_slice(&self) -> &[u8]
[src]
Get a slice from the buffer chunk, provided that the cannot exist any guard.
pub fn as_slice_mut(&mut self) -> &mut [u8]
[src]
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
fn borrow_mut(&mut self) -> &mut [u8]
[src]
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
C: AsBufferPool<I, H, E>,
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,
[src]
I: Integer,
G: Guard,
E: Copy,
H: Handle<I, E>,
C: AsBufferPool<I, H, E>,
M: Mode,
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,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
M: Mode,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
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>,
[src]
I: Integer,
H: Handle<I, E>,
E: Copy,
G: Guard,
C: AsBufferPool<I, H, E>,
fn data_shared(&self) -> &[u8]
[src]
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,
[src]
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,
[src]
I: Integer,
H: Send + Sync + Handle<I, E>,
E: Copy + Sync,
G: Sync + Guard,
C: AsBufferPool<I, H, E>,
M: Mode,
Auto Trait Implementations
impl<'pool, I, H, E, G = NoGuard, C = BufferPool<I, H, E>, M = Exclusive> !RefUnwindSafe for BufferSlice<'pool, I, H, E, G, C, M>
impl<'pool, I, H, E, G, C, M> Unpin for BufferSlice<'pool, I, H, E, G, C, M> where
E: Unpin,
G: Unpin,
I: Unpin,
M: Unpin,
E: Unpin,
G: Unpin,
I: Unpin,
M: Unpin,
impl<'pool, I, H, E, G = NoGuard, C = BufferPool<I, H, E>, M = Exclusive> !UnwindSafe for BufferSlice<'pool, I, H, E, G, C, M>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,