Struct alloc::raw_vec::RawVec

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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::dangling() on zero-sized types.
• Produces Unique::dangling() on zero-length allocations.
• Avoids freeing Unique::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::Unique 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: Unique<T>

🔬This is a nightly-only experimental API. (raw_vec_internals)

cap: usize

🔬This is a nightly-only experimental API. (raw_vec_internals)

alloc: A

🔬This is a nightly-only experimental API. (raw_vec_internals)

Implementations

impl<T> RawVec<T, Global>

pub const NEW: Self = _

🔬This is a nightly-only experimental API. (raw_vec_internals)

HACK(Centril): This exists because stable const fn can only call stable const fn, so they cannot call Self::new().

If you change RawVec<T>::new or dependencies, please take care to not introduce anything that would truly const-call something unstable.

pub const fn new() -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like with_capacity, but guarantees the buffer is zeroed.

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

pub(crate) const MIN_NON_ZERO_CAP: usize = _

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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>

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

pub fn capacity(&self) -> usize

🔬This is a nightly-only experimental API. (raw_vec_internals)

Gets the capacity of the allocation.

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

pub fn allocator(&self) -> &A

🔬This is a nightly-only experimental API. (raw_vec_internals)

Returns a shared reference to the allocator backing this RawVec.

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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)

🔬This is a nightly-only experimental API. (raw_vec_internals)

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>

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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>

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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)

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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

🔬This is a nightly-only experimental API. (raw_vec_internals)

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.