Trait presser::Slab

pub unsafe trait Slab {
    // Required methods
    fn base_ptr(&self) -> *const u8;
    fn base_ptr_mut(&mut self) -> *mut u8;
    fn size(&self) -> usize;

    // Provided methods
    fn as_maybe_uninit_bytes(&self) -> &[MaybeUninit<u8>] { ... }
    fn as_maybe_uninit_bytes_mut(&mut self) -> &mut [MaybeUninit<u8>] { ... }
    unsafe fn assume_initialized_as_bytes(&self) -> &[u8]  { ... }
    unsafe fn assume_initialized_as_bytes_mut(&mut self) -> &mut [u8]  { ... }
    unsafe fn assume_range_initialized_as_bytes<R>(&self, range: R) -> &[u8] 
       where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]> { ... }
    unsafe fn assume_range_initialized_as_bytes_mut<R>(
        &mut self,
        range: R
    ) -> &mut [u8] 
       where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]> { ... }
    fn as_ffi_buffer<R>(&self, range: R) -> (*const c_void, usize)
       where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]> { ... }
    fn as_ffi_readback_buffer<R>(&mut self, range: R) -> (*mut c_void, usize)
       where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]> { ... }
}

Represents a contiguous piece of a single allocation with some layout that is used as a data copying destination or reading source. May be wholly or partially uninitialized.

This trait is basically equivalent to implementing Deref/DerefMut with Target = [MaybeUninit<u8>] in terms of safety requirements. It is a separate trait for the extra flexibility having a trait we own provides: namely, the ability to implement it on foreign types.

It is implemented for a couple of built-in slab providers, as well as for [MaybeUninit<u8>], but the idea is that you can also implement this for your own data structure which can serve as a slab and then use that structure directly with presser’s helpers.

For built-in slabs, see RawAllocation, HeapSlab, and make_stack_slab.

Safety

Implementors of this trait must ensure these guarantees:

• The memory range represented by base_ptr and size may be wholly or partially uninitialized
• base_ptr must point to a valid, single allocation of at least size bytes.
  • Thus, size must return a size that, when added to base_ptr, stays within that single valid allocation.
• size must not be greater than isize::MAX

Assume the lifetime of a shared borrow of self is named 'a:

• base_ptr must be valid for 'a
• base_ptr must not be mutably aliased for 'a
  • It is necessary but not sufficient for this requirement that no outside mutable references may exist to its data, even if they are unused by user code.

Assume the lifetime of a mutable borrow of self is named 'a:

• base_ptr_mut must be valid for 'a
• base_ptr_mut must not be aliased at all for 'a
  • It is necessary but not sufficient for this requirement that no outside references may exist to its data, even if they are unused by user code.

Also see the crate-level safety documentation.

Required Methods

fn base_ptr(&self) -> *const u8

Get a pointer to the beginning of the allocation represented by self.

fn base_ptr_mut(&mut self) -> *mut u8

Get a pointer to the beginning of the allocation represented by self.

fn size(&self) -> usize

Get the size of the allocation represented by self.

Provided Methods

fn as_maybe_uninit_bytes(&self) -> &[MaybeUninit<u8>]

Interpret a portion of self as a slice of MaybeUninit<u8>. This is likely not incredibly useful, you probably want to use Slab::as_maybe_uninit_bytes_mut

fn as_maybe_uninit_bytes_mut(&mut self) -> &mut [MaybeUninit<u8>]

Interpret a portion of self as a mutable slice of MaybeUninit<u8>.

unsafe fn assume_initialized_as_bytes(&self) -> &[u8]

Interpret self as a byte slice. This assumes that all bytes in self are initialized.

Safety

Assuming that the safety guarantees for creating self were followed, the only extra requirement for this to be safe is that all memory within the range of self must be initialized. If any bytes within this range are not initialized, using this function is instantly undefined behavior, even if you do noting with the result.

Also see the crate-level Safety documentation for more.

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

Interpret self as a mutable byte slice. This assumes that all bytes in self are initialized.

Safety

Assuming that the safety guarantees for creating self were followed, the only extra requirement for this to be safe is that all memory within the range of self must be initialized. If any bytes within this range are not initialized, using this function is instantly undefined behavior, even if you do noting with the result.

Also see the crate-level Safety documentation for more.

unsafe fn assume_range_initialized_as_bytes<R>(&self, range: R) -> &[u8] where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]>,

Interpret a range of self as a byte slice. This assumes that all bytes within range are initialized.

In the future, this will hopefully not be needed as this operation will be equivalent to something like self.as_maybe_uninit_bytes_mut()[range].assume_init(), but the core/std implementation for this is still being scaffolded.

Safety

Assuming that the safety guarantees for creating self were followed, the only extra requirement for this to be safe is that all memory within range must be initialized. If any bytes within this range are not initialized, using this function is instantly undefined behavior, even if you do noting with the result.

Also see the crate-level Safety documentation for more.

unsafe fn assume_range_initialized_as_bytes_mut<R>( &mut self, range: R ) -> &mut [u8] where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]>,

Interpret a range of self as a mutable byte slice. This assumes that all bytes within range are initialized.

In the future, this will hopefully not be needed as this operation will be equivalent to something like self.as_maybe_uninit_bytes_mut()[range].assume_init(), but the core/std implementation for this is still being scaffolded.

Safety

Assuming that the safety guarantees for creating self were followed, the only extra requirement for this to be safe is that all memory within range must be initialized. If any bytes within this range are not initialized, using this function is instantly undefined behavior, even if you do noting with the result.

Also see the crate-level Safety documentation for more.

fn as_ffi_buffer<R>(&self, range: R) -> (*const c_void, usize)where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]>,

View a portion of self as a c_void pointer and size, appropriate for sending to an FFI function to have it read the contents of self. If you want the buffer to be filled with data from the other side of the ffi and then read it back, use as_ffi_readback_buffer instead.

Panics

Panics if the range is out of bounds of self

Safety

This function is safe in and of itself, but you must be careful not to use self for anything else while the returned pointer is in use by whatever you’re sending it to, and be sure that you’re upholding any alignment requirements needed.

fn as_ffi_readback_buffer<R>(&mut self, range: R) -> (*mut c_void, usize)where R: SliceIndex<[MaybeUninit<u8>], Output = [MaybeUninit<u8>]>,

View a portion of self as a c_void pointer and size, appropriate for sending to an FFI function to be filled and then read using one or more of the read_ helper functions.

You may want to use readback_from_ffi or [readback_sice_from_ffi] instead, which are even less prone to misuse.

Panics

Panics if the range is out of bounds of self

Safety

This function is safe in and of itself, but you must be careful not to use self for anything else while the returned pointer is in use by whatever you’re sending it to, and be sure that you’re upholding any alignment requirements needed.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<T> Slab for [MaybeUninit<T>]

fn base_ptr(&self) -> *const u8

fn base_ptr_mut(&mut self) -> *mut u8

fn size(&self) -> usize

Implementors

impl Slab for HeapSlab

Available on crate feature std only.

impl<'a> Slab for BorrowedRawAllocation<'a>