Struct allocator_api2::stable::raw_vec::RawVec

pub(crate) struct RawVec<T, A: Allocator = Global> {
    ptr: NonNull<T>,
    cap: usize,
    alloc: A,
}

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 NonNull::dangling() on zero-sized types.
• Produces NonNull::dangling() on zero-length allocations.
• Avoids freeing NonNull::dangling().
• 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.
• Calls handle_alloc_error for fallible allocations.
• Contains a ptr::NonNull and thus endows the user with all related benefits.
• Uses the excess returned from the allocator to use the largest available capacity.

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 the excess of a zero-sized types is always infinite, so capacity() always returns usize::MAX. This means that you need to be careful when round-tripping this type with a Box<[T]>, since capacity() won’t yield the length.

Fields

ptr: NonNull<T>

cap: usize

alloc: A

Implementations

impl<T> RawVec<T, Global>

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) -> Self

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.

Panics

Panics if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub fn with_capacity_zeroed(capacity: usize) -> Self

Like with_capacity, but guarantees the buffer is zeroed.

impl<T, A: Allocator> RawVec<T, A>

pub(crate) const MIN_NON_ZERO_CAP: usize = _

pub const fn new_in(alloc: A) -> Self

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

pub fn with_capacity_in(capacity: usize, alloc: A) -> Self

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

pub fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self

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

pub unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit<T>], A>

Converts the entire buffer into Box<[MaybeUninit<T>]> with the specified len.

Note that this will correctly reconstitute any cap changes that may have been performed. (See description of type for details.)

Safety

• len must be greater than or equal to the most recently requested capacity, and
• len must be less than or equal to self.capacity().

Note, that the requested capacity and self.capacity() could differ, as an allocator could overallocate and return a greater memory block than requested.

fn allocate_in(capacity: usize, init: AllocInit, alloc: A) -> Self

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

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

Safety

The ptr must be allocated (via the given allocator alloc), and with the given capacity. The capacity cannot exceed isize::MAX for sized types. (only a concern on 32-bit systems). ZST vectors may have a capacity up to usize::MAX. If the ptr and capacity come from a RawVec created via 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 NonNull::dangling() 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 allocator(&self) -> &A

Returns a shared reference to the allocator backing this RawVec.

fn current_memory(&self) -> Option<(NonNull<u8>, Layout)>

pub fn reserve(&mut self, len: usize, additional: usize)

Ensures that the buffer contains at least enough space to hold len + additional 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 len 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.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub fn reserve_for_push(&mut self, len: usize)

A specialized version of reserve() used only by the hot and oft-instantiated Vec::push(), which does its own capacity check.

pub fn try_reserve( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

The same as reserve, but returns on errors instead of panicking or aborting.

pub fn reserve_exact(&mut self, len: usize, additional: usize)

Ensures that the buffer contains at least enough space to hold len + additional elements. If it doesn’t already, will reallocate the minimum possible amount of memory necessary. Generally this will be exactly the amount of memory necessary, but in principle the allocator is free to give back more than we asked for.

If len 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.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub fn try_reserve_exact( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

The same as reserve_exact, but returns on errors instead of panicking or aborting.

pub fn shrink_to_fit(&mut self, cap: usize)

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

Panics

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

Aborts

Aborts on OOM.

impl<T, A: Allocator> RawVec<T, A>

fn needs_to_grow(&self, len: usize, additional: usize) -> bool

Returns if the buffer needs to grow to fulfill the needed extra capacity. Mainly used to make inlining reserve-calls possible without inlining grow.

fn set_ptr_and_cap(&mut self, ptr: NonNull<[u8]>, cap: usize)

fn grow_amortized( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

fn grow_exact( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

fn shrink(&mut self, cap: usize) -> Result<(), TryReserveError>

Trait Implementations

impl<T, A: Allocator> Drop for RawVec<T, A>

fn drop(&mut self)

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

impl<T, A> Send for RawVec<T, A>

where T: Send, A: Send + Allocator,

impl<T, A> Sync for RawVec<T, A>

where T: Sync, A: Sync + Allocator,