Struct bump_scope::Bump
source · pub struct Bump<A = Global, const MIN_ALIGN: usize = 1, const UP: bool = true, const GUARANTEED_ALLOCATED: bool = true>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,{ /* private fields */ }
Expand description
A bump allocator.
Most of Bump
’s constructors allocate memory.
The exception is Bump::unallocated
. A bump allocator created by this function has its GUARANTEED_ALLOCATED
parameter set to false
.
Such a Bump
is unable to create a scope with scoped
or scope_guard
.
It can be converted into a guaranteed allocated Bump
with into_guaranteed_allocated
or as_guaranteed_allocated_mut
.
§Gotchas
Allocating directly on a Bump
is not compatible with entering bump scopes at the same time:
let mut bump: Bump = Bump::new();
let one = bump.alloc(1);
bump.scoped(|bump| {
// whatever
});
Instead convert it to a BumpScope
first:
let mut bump: Bump = Bump::new();
let bump = bump.as_mut_scope();
let one = bump.alloc(1);
bump.scoped(|bump| {
// whatever
});
Implementations§
source§impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP, false>
impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP, false>
sourcepub const fn unallocated() -> Self
pub const fn unallocated() -> Self
Constructs a new Bump
without doing any allocations.
This is const
when the nightly-const-refs-to-static
feature is enabled.
source§impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED> + Default,
impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED> + Default,
sourcepub fn with_size(size: usize) -> Self
pub fn with_size(size: usize) -> Self
Constructs a new Bump
with a size hint for the first chunk.
If you want to ensure a specific capacity use with_capacity
instead.
The actual size that will be requested from the base allocator may be bigger or smaller.
(The size of [usize;2]
will be subtracted to make it friendlier towards its base allocator that may store its own header information along with it.)
§Panics
Panics if the allocation fails.
sourcepub fn with_capacity(layout: Layout) -> Self
pub fn with_capacity(layout: Layout) -> Self
sourcepub fn try_new() -> Result<Self, AllocError>
pub fn try_new() -> Result<Self, AllocError>
sourcepub fn try_with_size(size: usize) -> Result<Self, AllocError>
pub fn try_with_size(size: usize) -> Result<Self, AllocError>
Constructs a new Bump
with a size hint for the first chunk.
If you want to ensure a specific capacity use try_with_capacity
instead.
The actual size that will be requested from the base allocator may be bigger or smaller.
(The size of [usize;2]
will be subtracted to make it friendlier towards its base allocator that may store its own header information along with it.)
§Errors
Errors if the allocation fails.
sourcepub fn try_with_capacity(layout: Layout) -> Result<Self, AllocError>
pub fn try_with_capacity(layout: Layout) -> Result<Self, AllocError>
Constructs a new Bump
with at least enough space for layout
.
To construct a Bump
with some rough size estimate like 1 << 16
use try_with_size
instead.
§Errors
Errors if the allocation fails.
source§impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP>
impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP>
These functions are only available if the Bump
is guaranteed allocated.
sourcepub fn scoped<R>(
&mut self,
f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R,
) -> R
pub fn scoped<R>( &mut self, f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R, ) -> R
Calls f
with a new child scope.
§Examples
let mut bump: Bump = Bump::new();
bump.scoped(|bump| {
bump.alloc_str("Hello world!");
assert_eq!(bump.stats().allocated(), 12);
});
assert_eq!(bump.stats().allocated(), 0);
sourcepub fn scoped_aligned<const NEW_MIN_ALIGN: usize, R>(
&mut self,
f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R,
) -> Rwhere
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
pub fn scoped_aligned<const NEW_MIN_ALIGN: usize, R>(
&mut self,
f: impl FnOnce(BumpScope<'_, A, MIN_ALIGN, UP>) -> R,
) -> Rwhere
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
Calls f
with a new child scope of a new minimum alignment.
sourcepub fn scope_guard(&mut self) -> BumpScopeGuardRoot<'_, A, MIN_ALIGN, UP>
pub fn scope_guard(&mut self) -> BumpScopeGuardRoot<'_, A, MIN_ALIGN, UP>
Creates a new BumpScopeGuardRoot
.
This allows for creation of child scopes.
§Examples
let mut bump: Bump = Bump::new();
{
let mut guard = bump.scope_guard();
let bump = guard.scope();
bump.alloc_str("Hello world!");
assert_eq!(bump.stats().allocated(), 12);
}
assert_eq!(bump.stats().allocated(), 0);
sourcepub fn aligned<const NEW_MIN_ALIGN: usize, R>(
&mut self,
f: impl FnOnce(BumpScope<'_, A, NEW_MIN_ALIGN, UP>) -> R,
) -> Rwhere
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
pub fn aligned<const NEW_MIN_ALIGN: usize, R>(
&mut self,
f: impl FnOnce(BumpScope<'_, A, NEW_MIN_ALIGN, UP>) -> R,
) -> Rwhere
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
Calls f
with this scope but with a new minimum alignment.
sourcepub fn checkpoint(&self) -> Checkpoint
pub fn checkpoint(&self) -> Checkpoint
Creates a checkpoint of the current bump position.
§Examples
let checkpoint = bump.checkpoint();
{
let hello = bump.alloc_str("hello");
assert_eq!(bump.stats().allocated(), 5);
}
unsafe { bump.reset_to(checkpoint); }
assert_eq!(bump.stats().allocated(), 0);
sourcepub unsafe fn reset_to(&self, checkpoint: Checkpoint)
pub unsafe fn reset_to(&self, checkpoint: Checkpoint)
Resets the bump position to a previously created checkpoint. The memory that has been allocated since then will be reused by future allocations.
§Safety
- the checkpoint must have been created by this bump allocator
- the bump allocator must not have been
reset
since creation of this checkpoint - there must be no references to allocations made since creation of this checkpoint
sourcepub fn guaranteed_allocated_stats(&self) -> GuaranteedAllocatedStats<'_, UP>
pub fn guaranteed_allocated_stats(&self) -> GuaranteedAllocatedStats<'_, UP>
Returns a type which provides statistics about the memory usage of the bump allocator.
source§impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
sourcepub fn with_size_in(size: usize, allocator: A) -> Self
pub fn with_size_in(size: usize, allocator: A) -> Self
Constructs a new Bump
with a size hint for the first chunk.
If you want to ensure a specific capacity use with_capacity_in
instead.
The actual size that will be requested from the base allocator may be bigger or smaller.
(The size of [usize;2]
will be subtracted to make it friendlier towards its base allocator that may store its own header information along with it.)
§Panics
Panics if the allocation fails.
sourcepub fn with_capacity_in(layout: Layout, allocator: A) -> Self
pub fn with_capacity_in(layout: Layout, allocator: A) -> Self
Constructs a new Bump
with at least enough space for layout
.
To construct a Bump
with some rough size estimate like 1 << 16
use with_size_in
instead.
§Panics
Panics if the allocation fails.
sourcepub fn try_new_in(allocator: A) -> Result<Self, AllocError>
pub fn try_new_in(allocator: A) -> Result<Self, AllocError>
sourcepub fn try_with_size_in(size: usize, allocator: A) -> Result<Self, AllocError>
pub fn try_with_size_in(size: usize, allocator: A) -> Result<Self, AllocError>
Constructs a new Bump
with a size hint for the first chunk.
If you want to ensure a specific capacity use try_with_capacity_in
instead.
The actual size that will be requested from the base allocator may be bigger or smaller.
(The size of [usize;2]
will be subtracted to make it friendlier towards its base allocator that may store its own header information along with it.)
§Errors
Errors if the allocation fails.
sourcepub fn try_with_capacity_in(
layout: Layout,
allocator: A,
) -> Result<Self, AllocError>
pub fn try_with_capacity_in( layout: Layout, allocator: A, ) -> Result<Self, AllocError>
Constructs a new Bump
with at least enough space for layout
.
To construct a Bump
with some rough size estimate like 1 << 16
use try_with_size_in
instead.
§Errors
Errors if the allocation fails.
sourcepub fn reset(&mut self)
pub fn reset(&mut self)
This will only keep around the newest chunk, which is also the biggest.
sourcepub fn stats(&self) -> Stats<'_, UP>
pub fn stats(&self) -> Stats<'_, UP>
Returns a type which provides statistics about the memory usage of the bump allocator.
sourcepub fn without_dealloc(&self) -> WithoutDealloc<&Self>
pub fn without_dealloc(&self) -> WithoutDealloc<&Self>
Wraps &self
in WithoutDealloc
so that deallocate
becomes a no-op.
sourcepub fn without_shrink(&self) -> WithoutShrink<&Self>
pub fn without_shrink(&self) -> WithoutShrink<&Self>
Wraps &self
in WithoutShrink
so that shrink
becomes a no-op.
sourcepub fn as_scope(&self) -> &BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>
pub fn as_scope(&self) -> &BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>
Returns this &Bump
as a &BumpScope
.
sourcepub fn as_mut_scope(
&mut self,
) -> &mut BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>
pub fn as_mut_scope( &mut self, ) -> &mut BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>
Returns this &mut Bump
as a &mut BumpScope
.
sourcepub fn into_aligned<const NEW_MIN_ALIGN: usize>(
self,
) -> Bump<A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
pub fn into_aligned<const NEW_MIN_ALIGN: usize>(
self,
) -> Bump<A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
Converts this Bump
into a Bump
with a new minimum alignment.
sourcepub fn as_aligned_mut<const NEW_MIN_ALIGN: usize>(
&mut self,
) -> &mut Bump<A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
pub fn as_aligned_mut<const NEW_MIN_ALIGN: usize>(
&mut self,
) -> &mut Bump<A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,
Mutably borrows Bump
with a new minimum alignment.
This can not decrease the alignment. Trying to decrease alignment will result in a compile error. You can use aligned
or scoped_aligned
to decrease the alignment.
sourcepub fn into_guaranteed_allocated(self) -> Bump<A, MIN_ALIGN, UP>
pub fn into_guaranteed_allocated(self) -> Bump<A, MIN_ALIGN, UP>
sourcepub fn try_into_guaranteed_allocated(
self,
) -> Result<Bump<A, MIN_ALIGN, UP>, AllocError>
pub fn try_into_guaranteed_allocated( self, ) -> Result<Bump<A, MIN_ALIGN, UP>, AllocError>
sourcepub fn as_guaranteed_allocated_mut(&mut self) -> &mut Bump<A, MIN_ALIGN, UP>
pub fn as_guaranteed_allocated_mut(&mut self) -> &mut Bump<A, MIN_ALIGN, UP>
sourcepub fn try_as_guaranteed_allocated_mut(
&mut self,
) -> Result<&mut Bump<A, MIN_ALIGN, UP>, AllocError>
pub fn try_as_guaranteed_allocated_mut( &mut self, ) -> Result<&mut Bump<A, MIN_ALIGN, UP>, AllocError>
source§impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
sourcepub fn alloc_zeroed<T>(&self) -> BumpBox<'_, T> ⓘwhere
T: FromZeroes,
Available on crate feature zerocopy
only.
pub fn alloc_zeroed<T>(&self) -> BumpBox<'_, T> ⓘwhere
T: FromZeroes,
zerocopy
only.sourcepub fn alloc_zeroed_slice<T>(&self, len: usize) -> BumpBox<'_, [T]> ⓘwhere
T: FromZeroes,
Available on crate feature zerocopy
only.
pub fn alloc_zeroed_slice<T>(&self, len: usize) -> BumpBox<'_, [T]> ⓘwhere
T: FromZeroes,
zerocopy
only.sourcepub fn try_alloc_zeroed<T>(&self) -> Result<BumpBox<'_, T>, AllocError>where
T: FromZeroes,
Available on crate feature zerocopy
only.
pub fn try_alloc_zeroed<T>(&self) -> Result<BumpBox<'_, T>, AllocError>where
T: FromZeroes,
zerocopy
only.sourcepub fn try_alloc_zeroed_slice<T>(
&self,
len: usize,
) -> Result<BumpBox<'_, [T]>, AllocError>where
T: FromZeroes,
Available on crate feature zerocopy
only.
pub fn try_alloc_zeroed_slice<T>(
&self,
len: usize,
) -> Result<BumpBox<'_, [T]>, AllocError>where
T: FromZeroes,
zerocopy
only.source§impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
Functions to allocate. Available as fallible or infallible.
These require a guaranteed allocated bump allocator.
sourcepub fn alloc_with<T>(&self, f: impl FnOnce() -> T) -> BumpBox<'_, T> ⓘ
pub fn alloc_with<T>(&self, f: impl FnOnce() -> T) -> BumpBox<'_, T> ⓘ
Pre-allocate space for an object. Once space is allocated f
will be called to create the value to be put at that place.
In some situations this can help the compiler realize that T
can be constructed at the allocated space instead of having to copy it over.
§Panics
Panics if the allocation fails.
§Examples
let allocated = bump.alloc_with(|| 123);
assert_eq!(allocated, 123);
sourcepub fn alloc_default<T: Default>(&self) -> BumpBox<'_, T> ⓘ
pub fn alloc_default<T: Default>(&self) -> BumpBox<'_, T> ⓘ
Allocate an object with its default value.
This is equivalent to alloc_with(T::default)
.
§Panics
Panics if the allocation fails.
§Examples
let allocated = bump.alloc_default::<i32>();
assert_eq!(allocated, 0);
sourcepub fn alloc_slice_fill_with<T>(
&self,
len: usize,
f: impl FnMut() -> T,
) -> BumpBox<'_, [T]> ⓘ
pub fn alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> BumpBox<'_, [T]> ⓘ
Allocates a slice by fill it with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
Clone
a given value, use (try_)alloc_slice_fill
. If you want to use the Default
trait to generate values, you can pass Default::default
as the
argument.
§Panics
Panics if the allocation fails.
§Examples
let allocated = bump.alloc_slice_fill_with::<i32>(3, Default::default);
assert_eq!(allocated, [0, 0, 0]);
sourcepub fn alloc_fmt(&self, args: Arguments<'_>) -> BumpBox<'_, str> ⓘ
pub fn alloc_fmt(&self, args: Arguments<'_>) -> BumpBox<'_, str> ⓘ
Allocate a str
from format arguments.
For better performance prefer alloc_fmt_mut
.
§Panics
Panics if the allocation fails.
Panics if a formatting trait implementation returned an error.
§Examples
let one = 1;
let two = 2;
let string = bump.alloc_fmt(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, "1 + 2 = 3");
sourcepub fn alloc_fmt_mut(&mut self, args: Arguments<'_>) -> BumpBox<'_, str> ⓘ
pub fn alloc_fmt_mut(&mut self, args: Arguments<'_>) -> BumpBox<'_, str> ⓘ
Allocate a str
from format arguments.
Unlike alloc_fmt
, this function requires a mutable Bump(Scope)
.
§Panics
Panics if the allocation fails.
Panics if a formatting trait implementation returned an error.
§Examples
let one = 1;
let two = 2;
let string = bump.alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, "1 + 2 = 3");
sourcepub fn alloc_iter<T>(
&self,
iter: impl IntoIterator<Item = T>,
) -> BumpBox<'_, [T]> ⓘ
pub fn alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]> ⓘ
Allocate elements of an iterator into a slice.
For better performance prefer alloc_iter_exact
or alloc_iter_mut
.
§Panics
Panics if the allocation fails.
§Examples
let slice = bump.alloc_iter([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);
sourcepub fn alloc_iter_exact<T, I>(
&self,
iter: impl IntoIterator<Item = T, IntoIter = I>,
) -> BumpBox<'_, [T]> ⓘwhere
I: ExactSizeIterator<Item = T>,
pub fn alloc_iter_exact<T, I>(
&self,
iter: impl IntoIterator<Item = T, IntoIter = I>,
) -> BumpBox<'_, [T]> ⓘwhere
I: ExactSizeIterator<Item = T>,
sourcepub fn alloc_iter_mut<T>(
&mut self,
iter: impl IntoIterator<Item = T>,
) -> BumpBox<'_, [T]> ⓘ
pub fn alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]> ⓘ
Allocate elements of an iterator into a slice.
Unlike alloc_iter
, this function requires a mutable Bump(Scope)
.
When bumping downwards, prefer alloc_iter_mut_rev
or alloc_iter_exact
to avoid a shift of the slice.
§Panics
Panics if the allocation fails.
§Examples
let slice = bump.alloc_iter_mut([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);
sourcepub fn alloc_iter_mut_rev<T>(
&mut self,
iter: impl IntoIterator<Item = T>,
) -> BumpBox<'_, [T]> ⓘ
pub fn alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]> ⓘ
Allocate elements of an iterator into a slice in reverse order.
When bumping upwards, prefer alloc_iter_mut
or alloc_iter_exact
to avoid a shift of the slice.
§Panics
Panics if the allocation fails.
§Examples
let slice = bump.alloc_iter_mut_rev([1, 2, 3]);
assert_eq!(slice, [3, 2, 1]);
sourcepub fn alloc_uninit<T>(&self) -> BumpBox<'_, MaybeUninit<T>> ⓘ
pub fn alloc_uninit<T>(&self) -> BumpBox<'_, MaybeUninit<T>> ⓘ
Allocate an unitialized object.
You can safely initialize the object with init
or unsafely with assume_init
.
§Panics
Panics if the allocation fails.
§Examples
Safely:
let five = bump.alloc_uninit();
let five = five.init(5);
assert_eq!(*five, 5)
Unsafely:
let mut five = bump.alloc_uninit();
let five = unsafe {
five.write(5);
five.assume_init()
};
assert_eq!(*five, 5)
sourcepub fn alloc_uninit_slice<T>(&self, len: usize) -> BumpBox<'_, [MaybeUninit<T>]> ⓘ
pub fn alloc_uninit_slice<T>(&self, len: usize) -> BumpBox<'_, [MaybeUninit<T>]> ⓘ
Allocate an unitialized object slice.
You can safely initialize the object with
init_fill
,
init_fill_with
,
init_copy
,
init_clone
or unsafely with
assume_init
.
§Panics
Panics if the allocation fails.
§Examples
Safely:
let values = bump.alloc_uninit_slice(3);
let values = values.init_copy(&[1, 2, 3]);
assert_eq!(values, [1, 2, 3])
Unsafely:
let mut values = bump.alloc_uninit_slice(3);
let values = unsafe {
values[0].write(1);
values[1].write(2);
values[2].write(3);
values.assume_init()
};
assert_eq!(values, [1, 2, 3]);
sourcepub fn alloc_uninit_slice_for<T>(
&self,
slice: &[T],
) -> BumpBox<'_, [MaybeUninit<T>]> ⓘ
pub fn alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> BumpBox<'_, [MaybeUninit<T>]> ⓘ
Allocate an unitialized object slice.
You can safely initialize the object with
init_fill
,
init_fill_with
,
init_copy
,
init_clone
or unsafely with
assume_init
.
This is just like alloc_uninit_slice
but uses a slice
to provide the len
.
This avoids a check for a valid layout. The elements of slice
are irrelevant.
§Panics
Panics if the allocation fails.
§Examples
let slice = &[1, 2, 3];
let other_slice = bump.alloc_uninit_slice_for(slice);
assert_eq!(other_slice.len(), 3);
sourcepub fn alloc_fixed_vec<T>(&self, capacity: usize) -> FixedBumpVec<'_, T>
pub fn alloc_fixed_vec<T>(&self, capacity: usize) -> FixedBumpVec<'_, T>
Allocate a FixedBumpVec
with the given capacity
.
§Panics
Panics if the allocation fails.
§Examples
let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3])
sourcepub fn alloc_fixed_string(&self, capacity: usize) -> FixedBumpString<'_>
pub fn alloc_fixed_string(&self, capacity: usize) -> FixedBumpString<'_>
Allocate a FixedBumpString
with the given capacity
in bytes.
§Panics
Panics if the allocation fails.
§Examples
let mut string = bump.alloc_fixed_string(12);
string.push_str("Hello");
string.push_str(" world!");
assert_eq!(string, "Hello world!");
sourcepub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>
pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>
sourcepub fn reserve_bytes(&self, additional: usize)
pub fn reserve_bytes(&self, additional: usize)
Reserves capacity for at least additional
more bytes to be bump allocated.
The bump allocator may reserve more space to avoid frequent reallocations.
After calling reserve_bytes
, self.stats().remaining()
will be greater than or equal to
additional
. Does nothing if the capacity is already sufficient.
§Panics
Panics if the allocation fails.
§Examples
let bump: Bump = Bump::new();
assert!(bump.stats().capacity() < 4096);
bump.reserve_bytes(4096);
assert!(bump.stats().capacity() > 4096);
sourcepub fn try_alloc<T>(&self, value: T) -> Result<BumpBox<'_, T>, AllocError>
pub fn try_alloc<T>(&self, value: T) -> Result<BumpBox<'_, T>, AllocError>
sourcepub fn try_alloc_with<T>(
&self,
f: impl FnOnce() -> T,
) -> Result<BumpBox<'_, T>, AllocError>
pub fn try_alloc_with<T>( &self, f: impl FnOnce() -> T, ) -> Result<BumpBox<'_, T>, AllocError>
Pre-allocate space for an object. Once space is allocated f
will be called to create the value to be put at that place.
In some situations this can help the compiler realize that T
can be constructed at the allocated space instead of having to copy it over.
§Errors
Errors if the allocation fails.
§Examples
let allocated = bump.try_alloc_with(|| 123)?;
assert_eq!(allocated, 123);
sourcepub fn try_alloc_default<T: Default>(
&self,
) -> Result<BumpBox<'_, T>, AllocError>
pub fn try_alloc_default<T: Default>( &self, ) -> Result<BumpBox<'_, T>, AllocError>
Allocate an object with its default value.
This is equivalent to try_alloc_with(T::default)
.
§Errors
Errors if the allocation fails.
§Examples
let allocated = bump.try_alloc_default()?;
assert_eq!(allocated, 0);
sourcepub fn try_alloc_slice_copy<T: Copy>(
&self,
slice: &[T],
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_slice_copy<T: Copy>( &self, slice: &[T], ) -> Result<BumpBox<'_, [T]>, AllocError>
sourcepub fn try_alloc_slice_clone<T: Clone>(
&self,
slice: &[T],
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_slice_clone<T: Clone>( &self, slice: &[T], ) -> Result<BumpBox<'_, [T]>, AllocError>
sourcepub fn try_alloc_slice_fill<T: Clone>(
&self,
len: usize,
value: T,
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_slice_fill<T: Clone>( &self, len: usize, value: T, ) -> Result<BumpBox<'_, [T]>, AllocError>
sourcepub fn try_alloc_slice_fill_with<T>(
&self,
len: usize,
f: impl FnMut() -> T,
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> Result<BumpBox<'_, [T]>, AllocError>
Allocates a slice by fill it with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
Clone
a given value, use (try_)alloc_slice_fill
. If you want to use the Default
trait to generate values, you can pass Default::default
as the
argument.
§Errors
Errors if the allocation fails.
§Examples
let allocated = bump.try_alloc_slice_fill_with::<i32>(3, Default::default)?;
assert_eq!(allocated, [0, 0, 0]);
sourcepub fn try_alloc_str(&self, src: &str) -> Result<BumpBox<'_, str>, AllocError>
pub fn try_alloc_str(&self, src: &str) -> Result<BumpBox<'_, str>, AllocError>
sourcepub fn try_alloc_fmt(
&self,
args: Arguments<'_>,
) -> Result<BumpBox<'_, str>, AllocError>
pub fn try_alloc_fmt( &self, args: Arguments<'_>, ) -> Result<BumpBox<'_, str>, AllocError>
Allocate a str
from format arguments.
For better performance prefer try_alloc_fmt_mut
.
§Errors
Errors if the allocation fails.
Errors if a formatting trait implementation returned an error.
§Examples
let one = 1;
let two = 2;
let string = bump.try_alloc_fmt(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, "1 + 2 = 3");
sourcepub fn try_alloc_fmt_mut(
&mut self,
args: Arguments<'_>,
) -> Result<BumpBox<'_, str>, AllocError>
pub fn try_alloc_fmt_mut( &mut self, args: Arguments<'_>, ) -> Result<BumpBox<'_, str>, AllocError>
Allocate a str
from format arguments.
Unlike try_alloc_fmt
, this function requires a mutable Bump(Scope)
.
§Errors
Errors if the allocation fails.
Errors if a formatting trait implementation returned an error.
§Examples
let one = 1;
let two = 2;
let string = bump.try_alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, "1 + 2 = 3");
sourcepub fn try_alloc_iter<T>(
&self,
iter: impl IntoIterator<Item = T>,
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>
Allocate elements of an iterator into a slice.
For better performance prefer try_alloc_iter_exact
or try_alloc_iter_mut
.
§Errors
Errors if the allocation fails.
§Examples
let slice = bump.try_alloc_iter([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);
sourcepub fn try_alloc_iter_exact<T, I>(
&self,
iter: impl IntoIterator<Item = T, IntoIter = I>,
) -> Result<BumpBox<'_, [T]>, AllocError>where
I: ExactSizeIterator<Item = T>,
pub fn try_alloc_iter_exact<T, I>(
&self,
iter: impl IntoIterator<Item = T, IntoIter = I>,
) -> Result<BumpBox<'_, [T]>, AllocError>where
I: ExactSizeIterator<Item = T>,
sourcepub fn try_alloc_iter_mut<T>(
&mut self,
iter: impl IntoIterator<Item = T>,
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>
Allocate elements of an iterator into a slice.
Unlike try_alloc_iter
, this function requires a mutable Bump(Scope)
.
When bumping downwards, prefer try_alloc_iter_mut_rev
or try_alloc_iter_exact
to avoid a shift of the slice.
§Errors
Errors if the allocation fails.
§Examples
let slice = bump.try_alloc_iter_mut([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);
sourcepub fn try_alloc_iter_mut_rev<T>(
&mut self,
iter: impl IntoIterator<Item = T>,
) -> Result<BumpBox<'_, [T]>, AllocError>
pub fn try_alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>
Allocate elements of an iterator into a slice in reverse order.
When bumping upwards, prefer try_alloc_iter_mut
or try_alloc_iter_exact
to avoid a shift of the slice.
§Errors
Errors if the allocation fails.
§Examples
let slice = bump.try_alloc_iter_mut_rev([1, 2, 3])?;
assert_eq!(slice, [3, 2, 1]);
sourcepub fn try_alloc_uninit<T>(
&self,
) -> Result<BumpBox<'_, MaybeUninit<T>>, AllocError>
pub fn try_alloc_uninit<T>( &self, ) -> Result<BumpBox<'_, MaybeUninit<T>>, AllocError>
Allocate an unitialized object.
You can safely initialize the object with init
or unsafely with assume_init
.
§Errors
Errors if the allocation fails.
§Examples
Safely:
let five = bump.try_alloc_uninit()?;
let five = five.init(5);
assert_eq!(*five, 5);
Unsafely:
let mut five = bump.try_alloc_uninit()?;
let five = unsafe {
five.write(5);
five.assume_init()
};
assert_eq!(*five, 5);
sourcepub fn try_alloc_uninit_slice<T>(
&self,
len: usize,
) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>
pub fn try_alloc_uninit_slice<T>( &self, len: usize, ) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>
Allocate an unitialized object slice.
You can safely initialize the object with
init_fill
,
init_fill_with
,
init_copy
,
init_clone
or unsafely with
assume_init
.
§Errors
Errors if the allocation fails.
§Examples
Safely:
let values = bump.try_alloc_uninit_slice(3)?;
let values = values.init_copy(&[1, 2, 3]);
assert_eq!(values, [1, 2, 3]);
Unsafely:
let mut values = bump.try_alloc_uninit_slice(3)?;
let values = unsafe {
values[0].write(1);
values[1].write(2);
values[2].write(3);
values.assume_init()
};
assert_eq!(values, [1, 2, 3]);
sourcepub fn try_alloc_uninit_slice_for<T>(
&self,
slice: &[T],
) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>
pub fn try_alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>
Allocate an unitialized object slice.
You can safely initialize the object with
init_fill
,
init_fill_with
,
init_copy
,
init_clone
or unsafely with
assume_init
.
This is just like try_alloc_uninit_slice
but uses a slice
to provide the len
.
This avoids a check for a valid layout. The elements of slice
are irrelevant.
§Errors
Errors if the allocation fails.
§Examples
let slice = &[1, 2, 3];
let other_slice = bump.try_alloc_uninit_slice_for(slice)?;
assert_eq!(other_slice.len(), 3);
sourcepub fn try_alloc_fixed_vec<T>(
&self,
capacity: usize,
) -> Result<FixedBumpVec<'_, T>, AllocError>
pub fn try_alloc_fixed_vec<T>( &self, capacity: usize, ) -> Result<FixedBumpVec<'_, T>, AllocError>
Allocate a FixedBumpVec
with the given capacity
.
§Errors
Errors if the allocation fails.
§Examples
let mut values = bump.try_alloc_fixed_vec(3)?;
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3]);
sourcepub fn try_alloc_fixed_string(
&self,
capacity: usize,
) -> Result<FixedBumpString<'_>, AllocError>
pub fn try_alloc_fixed_string( &self, capacity: usize, ) -> Result<FixedBumpString<'_>, AllocError>
Allocate a FixedBumpString
with the given capacity
in bytes.
§Errors
Errors if the allocation fails.
§Examples
let mut string = bump.try_alloc_fixed_string(12)?;
string.push_str("Hello");
string.push_str(" world!");
assert_eq!(string, "Hello world!");
sourcepub fn try_alloc_layout(
&self,
layout: Layout,
) -> Result<NonNull<u8>, AllocError>
pub fn try_alloc_layout( &self, layout: Layout, ) -> Result<NonNull<u8>, AllocError>
sourcepub fn try_reserve_bytes(&self, additional: usize) -> Result<(), AllocError>
pub fn try_reserve_bytes(&self, additional: usize) -> Result<(), AllocError>
Reserves capacity for at least additional
more bytes to be bump allocated.
The bump allocator may reserve more space to avoid frequent reallocations.
After calling reserve_bytes
, self.stats().remaining()
will be greater than or equal to
additional
. Does nothing if the capacity is already sufficient.
§Errors
Errors if the allocation fails.
§Examples
let bump: Bump = Bump::try_new()?;
assert!(bump.stats().capacity() < 4096);
bump.try_reserve_bytes(4096)?;
assert!(bump.stats().capacity() > 4096);
source§impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP>
impl<A, const MIN_ALIGN: usize, const UP: bool> Bump<A, MIN_ALIGN, UP>
Functions to allocate. Available as fallible or infallible.
These require a guaranteed allocated bump allocator.
sourcepub fn alloc_try_with<T, E>(
&self,
f: impl FnOnce() -> Result<T, E>,
) -> Result<BumpBox<'_, T>, E>
pub fn alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'_, T>, E>
Allocates the result of f
in the bump allocator, then moves E
out of it and deallocates the space it took up.
This can be more performant than allocating T
after the fact, as Result<T, E>
may be constructed in the bump allocators memory instead of on the stack and then copied over.
There is also alloc_try_with_mut
, optimized for a mutable reference.
§Panics
Panics if the allocation fails.
§Examples
let result = bump.alloc_try_with(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());
let result = bump.alloc_try_with(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);
sourcepub fn alloc_try_with_mut<T, E>(
&mut self,
f: impl FnOnce() -> Result<T, E>,
) -> Result<BumpBox<'_, T>, E>
pub fn alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'_, T>, E>
Allocates the result of f
in the bump allocator, then moves E
out of it and deallocates the space it took up.
This can be more performant than allocating T
after the fact, as Result<T, E>
may be constructed in the bump allocators memory instead of on the stack and then copied over.
This is just like alloc_try_with
, but optimized for a mutable reference.
§Panics
Panics if the allocation fails.
§Examples
let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());
let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);
sourcepub fn try_alloc_try_with<T, E>(
&self,
f: impl FnOnce() -> Result<T, E>,
) -> Result<Result<BumpBox<'_, T>, E>, AllocError>
pub fn try_alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'_, T>, E>, AllocError>
Allocates the result of f
in the bump allocator, then moves E
out of it and deallocates the space it took up.
This can be more performant than allocating T
after the fact, as Result<T, E>
may be constructed in the bump allocators memory instead of on the stack and then copied over.
There is also try_alloc_try_with_mut
, optimized for a mutable reference.
§Errors
Errors if the allocation fails.
§Examples
let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());
let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);
sourcepub fn try_alloc_try_with_mut<T, E>(
&mut self,
f: impl FnOnce() -> Result<T, E>,
) -> Result<Result<BumpBox<'_, T>, E>, AllocError>
pub fn try_alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'_, T>, E>, AllocError>
Allocates the result of f
in the bump allocator, then moves E
out of it and deallocates the space it took up.
This can be more performant than allocating T
after the fact, as Result<T, E>
may be constructed in the bump allocators memory instead of on the stack and then copied over.
This is just like try_alloc_try_with
, but optimized for a mutable reference.
§Errors
Errors if the allocation fails.
§Examples
let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());
let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);
Trait Implementations§
source§impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Allocator for Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool> Allocator for Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>where
MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
A: BaseAllocator<GUARANTEED_ALLOCATED>,
source§fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
allocator_api
)source§unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)
unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)
allocator_api
)ptr
. Read moresource§unsafe fn grow(
&self,
ptr: NonNull<u8>,
old_layout: Layout,
new_layout: Layout,
) -> Result<NonNull<[u8]>, AllocError>
unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>
allocator_api
)source§unsafe fn grow_zeroed(
&self,
ptr: NonNull<u8>,
old_layout: Layout,
new_layout: Layout,
) -> Result<NonNull<[u8]>, AllocError>
unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>
allocator_api
)grow
, but also ensures that the new contents are set to zero before being
returned. Read moresource§unsafe fn shrink(
&self,
ptr: NonNull<u8>,
old_layout: Layout,
new_layout: Layout,
) -> Result<NonNull<[u8]>, AllocError>
unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>
allocator_api
)source§fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
allocator_api
)allocate
, but also ensures that the returned memory is zero-initialized. Read more