Struct alloc_wg::raw_vec::RawVec

pub struct RawVec<T, B: BuildAllocRef = Global> { /* fields omitted */ }

A low-level utility for more ergonomically allocating, reallocating, and deallocating a buffer of memory on the heap without having to worry about all the corner cases involved. This type is excellent for building your own data structures like Vec and VecDeque. In particular:

• Produces Unique::empty() on zero-sized types
• Produces Unique::empty() on zero-length allocations
• Catches all overflows in capacity computations (promotes them to "capacity overflow" panics)
• Guards against 32-bit systems allocating more than isize::MAX bytes
• Guards against overflowing your length
• Aborts on OOM or calls handle_alloc_error as applicable
• Avoids freeing Unique::empty()
• Contains a ptr::Unique and thus endows the user with all related benefits

This type does not in anyway inspect the memory that it manages. When dropped it will free its memory, but it won't try to Drop its contents. It is up to the user of RawVec to handle the actual things stored inside of a RawVec.

Note that a RawVec always forces its capacity to be usize::MAX for zero-sized types. This enables you to use capacity growing logic catch the overflows in your length that might occur with zero-sized types.

However this means that you need to be careful when round-tripping this type with a Box<[T]>: capacity() won't yield the len. However with_capacity, shrink_to_fit, and from_box will actually set RawVec's private capacity field. This allows zero-sized types to not be special-cased by consumers of this type.

Methods

impl<T> RawVec<T>

pub const NEW: Self

HACK(Centril): This exists because #[unstable] const fns needn't conform to min_const_fn and so they cannot be called in min_const_fns either.

If you change RawVec<T>::new or dependencies, please take care to not introduce anything that would truly violate min_const_fn.

NOTE: We could avoid this hack and check conformance with some #[rustc_force_min_const_fn] attribute which requires conformance with min_const_fn but does not necessarily allow calling it in stable(...) const fn / user code not enabling foo when #[rustc_const_unstable(feature = "foo", ..)] is present.

pub const fn new() -> Self

Creates the biggest possible RawVec (on the system heap) without allocating. If T has positive size, then this makes a RawVec with capacity 0. If T is zero-sized, then it makes a RawVec with capacity usize::MAX. Useful for implementing delayed allocation.

pub fn with_capacity(
    capacity: usize
) -> Result<Self, CollectionAllocErr<Global>>

Creates a RawVec (on the system heap) with exactly the capacity and alignment requirements for a [T; capacity]. This is equivalent to calling RawVec::new when capacity is 0 or T is zero-sized. Note that if T is zero-sized this means you will not get a RawVec with the requested capacity.

Errors

• CapacityOverflow if the requested capacity exceeds usize::MAX bytes.
• CapacityOverflow on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.
• AllocError on OOM

pub fn with_capacity_zeroed(
    capacity: usize
) -> Result<Self, CollectionAllocErr<Global>>

Like with_capacity, but guarantees the buffer is zeroed.

pub unsafe fn from_raw_parts(ptr: *mut T, capacity: usize) -> Self

Reconstitutes a RawVec from a pointer, and capacity.

Safety

The ptr must be allocated (via the default allocator Global), and with the given capacity. The capacity cannot exceed isize::MAX (only a concern on 32-bit systems). If the ptr and capacity come from a RawVec created with Global, then this is guaranteed.

impl<T, B: BuildAllocRef> RawVec<T, B> where
    B::Ref: AllocRef, 

pub fn new_in(a: B::Ref) -> Self

Like new but parameterized over the choice of allocator for the returned RawVec.

pub fn with_capacity_in(
    capacity: usize,
    a: B::Ref
) -> Result<Self, CollectionAllocErr<B>>

Like with_capacity but parameterized over the choice of allocator for the returned RawVec.

pub fn with_capacity_zeroed_in(
    capacity: usize,
    a: B::Ref
) -> Result<Self, CollectionAllocErr<B>>

Like with_capacity_zeroed but parameterized over the choice of allocator for the returned RawVec.

impl<T, B: BuildAllocRef> RawVec<T, B>

pub unsafe fn from_raw_parts_in(
    ptr: *mut T,
    capacity: usize,
    build_alloc: B
) -> Self

Reconstitutes a RawVec from a pointer, capacity, and allocator.

Safety

The ptr must be allocated (via the given allocator build_alloc), and with the given capacity. The capacity cannot exceed isize::MAX (only a concern on 32-bit systems). If the ptr and capacity come from a RawVec created via build_alloc, then this is guaranteed.

pub fn ptr(&self) -> *mut T

Gets a raw pointer to the start of the allocation. Note that this is Unique::empty() if capacity = 0 or T is zero-sized. In the former case, you must be careful.

pub fn capacity(&self) -> usize

Gets the capacity of the allocation.

This will always be usize::MAX if T is zero-sized.

pub fn build_alloc(&self) -> &B

Returns a shared reference to the alloc builder.

pub fn build_alloc_mut(&mut self) -> &mut B

Returns a mutable reference to the alloc builder.

pub fn alloc_ref(&mut self) -> (B::Ref, Option<NonZeroLayout>)

Returns the allocator used by this RawVec and the used layout, if any. The layout is None if the capacity of this RawVec is 0 or if T is a zero sized type.

impl<T, B: BuildAllocRef> RawVec<T, B> where
    B::Ref: ReallocRef, 

pub fn reserve(
    &mut self,
    used_capacity: usize,
    needed_extra_capacity: usize
) -> Result<(), CollectionAllocErr<B>>

Ensures that the buffer contains at least enough space to hold used_capacity + needed_extra_capacity elements. If it doesn't already have enough capacity, will reallocate enough space plus comfortable slack space to get amortized O(1) behavior. Will limit this behavior if it would needlessly cause itself to panic.

If used_capacity exceeds self.capacity(), this may fail to actually allocate the requested space. This is not really unsafe, but the unsafe code you write that relies on the behavior of this function may break.

This is ideal for implementing a bulk-push operation like extend.

Errors

• CapacityOverflow if the requested capacity exceeds usize::MAX bytes.
• CapacityOverflow on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.
• AllocError on OOM

Examples

use alloc_wg::{alloc::Global, collections::CollectionAllocErr, raw_vec::RawVec};
use core::ptr;

struct MyVec<T> {
    buf: RawVec<T>,
    len: usize,
}

impl<T: Clone> MyVec<T> {
    pub fn push_all(&mut self, elems: &[T]) -> Result<(), CollectionAllocErr<Global>> {
        self.buf.reserve(self.len, elems.len())?;
        // reserve would have aborted or panicked if the len exceeded
        // `isize::MAX` so this is safe to do unchecked now.
        for x in elems {
            unsafe {
                ptr::write(self.buf.ptr().add(self.len), x.clone());
            }
            self.len += 1;
        }
        Ok(())
    }
}

pub fn reserve_exact(
    &mut self,
    used_capacity: usize,
    needed_extra_capacity: usize
) -> Result<(), CollectionAllocErr<B>>

Attempts to ensure that the buffer contains at least enough space to hold used_capacity + needed_extra_capacity elements. If it doesn't already have enough capacity, will reallocate in place enough space plus comfortable slack space to get amortized O(1) behavior. Will limit this behaviour if it would needlessly cause itself to panic.

If used_capacity exceeds self.capacity(), this may fail to actually allocate the requested space. This is not really unsafe, but the unsafe code you write that relies on the behavior of this function may break.

Returns true if the reallocation attempt has succeeded.

Errors

• CapacityOverflow if the requested capacity exceeds usize::MAX bytes.
• CapacityOverflow on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.
• AllocError on OOM

pub fn shrink_to_fit(
    &mut self,
    amount: usize
) -> Result<(), CollectionAllocErr<B>>

Shrinks the allocation down to the specified amount. If the given amount is 0, actually completely deallocates.

Panics

Panics if the given amount is larger than the current capacity.

Errors

• AllocError on OOM

impl<T, B: BuildAllocRef> RawVec<T, B>

pub unsafe fn dealloc_buffer(&mut self)

Frees the memory owned by the RawVec without trying to Drop its contents.

Trait Implementations

impl<T, B: BuildAllocRef> Drop for RawVec<T, B>

fn drop(&mut self)

Frees the memory owned by the RawVec without trying to Drop its contents.

impl<T, B: BuildAllocRef> From<Box<[T], B>> for RawVec<T, B>

fn from(slice: Box<[T], B>) -> Self

Performs the conversion.

impl<T, B: BuildAllocRef> From<RawVec<T, B>> for Box<[MaybeUninit<T>], B>

fn from(vec: RawVec<T, B>) -> Self

Performs the conversion.