Struct BufferInitializer

pub struct BufferInitializer<T> { /* private fields */ }

An initialized tracking a container type that dereferences into a slice of possibly-uninitialized items, and how many items have been initialized, respectively. The inner data can always be moved out as uninitialized, but when the buffer has been fully initialized, the buffer can be turned into the initialized equivalent.

Implementations

impl<T> BufferInitializer<T>

pub const fn uninit(inner: T) -> Self

Wrap a possibly-uninitialized buffer into the initializer, with the current initialization cursor set to zero.

pub fn into_inner(self) -> T

pub const fn items_initialized(&self) -> usize

impl<T, Item> BufferInitializer<AsUninit<T>>

where T: Deref<Target = [Item]> + DerefMut + TrustedDeref,

pub fn new(init: T) -> Self

Construct an initializer to a container that is already initialized. This ensures that no bytes will be filled with zeroes, as they do not have to.

impl<T> BufferInitializer<T>

where T: Initialize,

pub unsafe fn advance(&mut self, count: usize)

Advance the initialization counter by count items.

Safety

For this to be safe, the caller must be sure that another count items from the previous initialization offset, are initialized.

This method does not do any bounds checking. Ergo, count can never be larger than the value returned by remaining.

pub unsafe fn advance_to_end(&mut self)

Advance the initialization counter to the end.

Safety

While this eliminates the need for the caller to bounds check manually, unlike with advance, the caller must uphold the initialization invariant.

pub unsafe fn assume_init(self) -> AssertInit<T>

Assume that the inner value is fully initialized, finalizing the original type into its initialized counterpart.

Safety

The caller must uphold the initialization invariant.

pub fn into_raw_parts(self) -> (T, usize)

pub fn all_uninit(&self) -> &[MaybeUninit<T::Item>]

Retrieve a slice of a possibly uninitialized items, over the entire buffer.

pub unsafe fn all_uninit_mut(&mut self) -> &mut [MaybeUninit<T::Item>]

Retrieve a mutable slice of a possibly uninitialized items, over the entire buffer.

Safety

This is unsafe, because the caller must not de-initialize the slice as the API also promises the initialized region to always actually be initialized.

pub fn capacity(&self) -> usize

Get the total size of the buffer that is being initialized.

pub fn remaining(&self) -> usize

Get the number of items that must be filled before the buffer gets fully initialized, and can be turned into an initialized type (e.g. Box<[U]>).

pub fn is_completely_init(&self) -> bool

Check whether the buffer is completely initialized. Note that this is unrelated to it being filled.

pub fn is_completely_uninit(&self) -> bool

Check whether no single item of the buffer has been initialized.

pub fn uninit_part(&self) -> &[MaybeUninit<T::Item>]

Retrieve a shared reference to the uninitialized part of the buffer. This is only included for completeness, since apart from some corner cases where one does not have exclusive access to the buffer but still wants to initialize it, is rather useless.

pub fn init_part(&self) -> &[T::Item]

Retrieve a shared slice to the initialized part of the buffer. Note that this is different from the filled part, as a buffer can be fully initialized but not filled.

pub fn uninit_part_mut(&mut self) -> &mut [MaybeUninit<T::Item>]

Get a mutable slice to the uninitialized part of the buffer. Note that this is different from the unfilled part of it.

pub fn init_part_mut(&mut self) -> &mut [T::Item]

Retrieve a mutable slice to the initialized part of the buffer. Note that this is not the same as the filled part.

pub fn try_into_init(self) -> Result<AssertInit<T>, Self>

Try to transform the initializing type, into its initialized counterpart, provided that the it has been fully initialized.

pub fn finish_init_by_filling(self, item: T::Item) -> AssertInit<T>

where T::Item: Copy,

Finish the initialization by writing item to the uninitialized region, and then get the final initialized type.

pub fn fill_uninit_part(&mut self, item: T::Item)

where T::Item: Copy,

Fill the uninitialized part with copies of item (memset).

After this method has been called, it is safe to assume_init. try_into_init will then also succeed.

pub fn partially_fill_uninit_part(&mut self, count: usize, item: T::Item)

where T::Item: Copy,

pub fn init_uninit_parts(&self) -> (&[T::Item], &[MaybeUninit<T::Item>])

Get both the initialized and uninitialized parts simultaneously. This method is nothing but a shorthand for the individual methods, but included for completeness.

This is because the mutable counterpart init_uninit_parts_mut cannot be done separately by calling the init_part_mut and uninit_part_mut methods.

pub fn init_uninit_parts_mut( &mut self, ) -> (&mut [T::Item], &mut [MaybeUninit<T::Item>])

Borrow both the initialized as well as the uninitialized parts, mutably.

impl<T> BufferInitializer<T>

where T: Initialize<Item = u8>,

pub fn finish_init_by_zeroing(self) -> AssertInit<T>

Finish the initialization by zeroing uninitialized region, and then get the final initialized type.

pub fn partially_zero_uninit_part(&mut self, count: usize)

pub fn zero_uninit_part(&mut self)

Zero the uninitialized part.

After this method has been called, it is safe to assume_init. try_into_init will then also succeed.

Trait Implementations

impl<T: Debug> Debug for BufferInitializer<T>

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

Formats the value using the given formatter.