pub(crate) struct RawVec<T, A: Allocator = Global> {
ptr: Unique<T>,
cap: usize,
alloc: A,
}
raw_vec_internals
)Expand description
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>
raw_vec_internals
)cap: usize
raw_vec_internals
)alloc: A
raw_vec_internals
)Implementations§
source§impl<T> RawVec<T, Global>
impl<T> RawVec<T, Global>
sourcepub const NEW: Self = _
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub const NEW: Self = _
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.
sourcepub const fn new() -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub const fn new() -> Self
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.
sourcepub fn with_capacity(capacity: usize) -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn with_capacity(capacity: usize) -> Self
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.
sourcepub fn with_capacity_zeroed(capacity: usize) -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn with_capacity_zeroed(capacity: usize) -> Self
raw_vec_internals
)Like with_capacity
, but guarantees the buffer is zeroed.
source§impl<T, A: Allocator> RawVec<T, A>
impl<T, A: Allocator> RawVec<T, A>
pub(crate) const MIN_NON_ZERO_CAP: usize = _
raw_vec_internals
)sourcepub const fn new_in(alloc: A) -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub const fn new_in(alloc: A) -> Self
raw_vec_internals
)Like new
, but parameterized over the choice of allocator for
the returned RawVec
.
sourcepub fn with_capacity_in(capacity: usize, alloc: A) -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn with_capacity_in(capacity: usize, alloc: A) -> Self
raw_vec_internals
)Like with_capacity
, but parameterized over the choice of
allocator for the returned RawVec
.
sourcepub fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self
raw_vec_internals
)Like with_capacity_zeroed
, but parameterized over the choice
of allocator for the returned RawVec
.
sourcepub unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit<T>], A>
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit<T>], A>
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, andlen
must be less than or equal toself.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
raw_vec_internals
)sourcepub unsafe fn from_raw_parts_in(ptr: *mut T, capacity: usize, 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
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.
sourcepub fn ptr(&self) -> *mut T
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn ptr(&self) -> *mut T
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.
sourcepub fn capacity(&self) -> usize
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn capacity(&self) -> usize
raw_vec_internals
)Gets the capacity of the allocation.
This will always be usize::MAX
if T
is zero-sized.
sourcepub fn allocator(&self) -> &A
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn allocator(&self) -> &A
raw_vec_internals
)Returns a shared reference to the allocator backing this RawVec
.
fn current_memory(&self) -> Option<(NonNull<u8>, Layout)>
raw_vec_internals
)sourcepub fn reserve(&mut self, len: usize, additional: usize)
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn reserve(&mut self, len: usize, additional: usize)
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.
sourcepub fn reserve_for_push(&mut self, len: usize)
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn reserve_for_push(&mut self, len: usize)
raw_vec_internals
)A specialized version of reserve()
used only by the hot and
oft-instantiated Vec::push()
, which does its own capacity check.
sourcepub fn try_reserve(
&mut self,
len: usize,
additional: usize
) -> Result<(), TryReserveError>
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn try_reserve( &mut self, len: usize, additional: usize ) -> Result<(), TryReserveError>
raw_vec_internals
)The same as reserve
, but returns on errors instead of panicking or aborting.
sourcepub fn reserve_exact(&mut self, len: usize, additional: usize)
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn reserve_exact(&mut self, len: usize, additional: usize)
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.
sourcepub fn try_reserve_exact(
&mut self,
len: usize,
additional: usize
) -> Result<(), TryReserveError>
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn try_reserve_exact( &mut self, len: usize, additional: usize ) -> Result<(), TryReserveError>
raw_vec_internals
)The same as reserve_exact
, but returns on errors instead of panicking or aborting.
sourcepub fn shrink_to_fit(&mut self, cap: usize)
🔬This is a nightly-only experimental API. (raw_vec_internals
)
pub fn shrink_to_fit(&mut self, cap: usize)
raw_vec_internals
)source§impl<T, A: Allocator> RawVec<T, A>
impl<T, A: Allocator> RawVec<T, A>
sourcefn needs_to_grow(&self, len: usize, additional: usize) -> bool
🔬This is a nightly-only experimental API. (raw_vec_internals
)
fn needs_to_grow(&self, len: usize, additional: usize) -> bool
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)
raw_vec_internals
)fn grow_amortized( &mut self, len: usize, additional: usize ) -> Result<(), TryReserveError>
raw_vec_internals
)fn grow_exact( &mut self, len: usize, additional: usize ) -> Result<(), TryReserveError>
raw_vec_internals
)fn shrink(&mut self, cap: usize) -> Result<(), TryReserveError>
raw_vec_internals
)