pub struct Allocator { /* private fields */ }
Expand description
The actual storage for FastAlloc.
Implementations§
source§impl Allocator
impl Allocator
sourcepub unsafe fn guard(&self) -> AllocGuard
pub unsafe fn guard(&self) -> AllocGuard
Creates a RAII guard that enables optimized allocation.
§Safety
Allocator must outlive crate::boxed::Box and crate::vec::Vec created while the guard is active.
Methods from Deref<Target = Bump>§
pub fn allocation_limit(&self) -> Option<usize>
pub fn allocation_limit(&self) -> Option<usize>
The allocation limit for this arena in bytes.
§Example
let bump = bumpalo::Bump::with_capacity(0);
assert_eq!(bump.allocation_limit(), None);
bump.set_allocation_limit(Some(6));
assert_eq!(bump.allocation_limit(), Some(6));
bump.set_allocation_limit(None);
assert_eq!(bump.allocation_limit(), None);
pub fn set_allocation_limit(&self, limit: Option<usize>)
pub fn set_allocation_limit(&self, limit: Option<usize>)
Set the allocation limit in bytes for this arena.
The allocation limit is only enforced when allocating new backing chunks for
a Bump
. Updating the allocation limit will not affect existing allocations
or any future allocations within the Bump
’s current chunk.
§Example
let bump = bumpalo::Bump::with_capacity(0);
bump.set_allocation_limit(Some(0));
assert!(bump.try_alloc(5).is_err());
pub fn reset(&mut self)
pub fn reset(&mut self)
Reset this bump allocator.
Performs mass deallocation on everything allocated in this arena by
resetting the pointer into the underlying chunk of memory to the start
of the chunk. Does not run any Drop
implementations on deallocated
objects; see the top-level documentation for details.
If this arena has allocated multiple chunks to bump allocate into, then the excess chunks are returned to the global allocator.
§Example
let mut bump = bumpalo::Bump::new();
// Allocate a bunch of things.
{
for i in 0..100 {
bump.alloc(i);
}
}
// Reset the arena.
bump.reset();
// Allocate some new things in the space previously occupied by the
// original things.
for j in 200..400 {
bump.alloc(j);
}
pub fn alloc_with<F, T>(&self, f: F) -> &mut Twhere
F: FnOnce() -> T,
pub fn alloc_with<F, T>(&self, f: F) -> &mut Twhere
F: FnOnce() -> T,
Pre-allocate space for an object in this Bump
, initializes it using
the closure, then returns an exclusive reference to it.
See The _with
Method Suffix for a
discussion on the differences between the _with
suffixed methods and
those methods without it, their performance characteristics, and when
you might or might not choose a _with
suffixed method.
§Panics
Panics if reserving space for T
fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.alloc_with(|| "hello");
assert_eq!(*x, "hello");
pub fn try_alloc_with<F, T>(&self, f: F) -> Result<&mut T, AllocErr>where
F: FnOnce() -> T,
pub fn try_alloc_with<F, T>(&self, f: F) -> Result<&mut T, AllocErr>where
F: FnOnce() -> T,
Tries to pre-allocate space for an object in this Bump
, initializes
it using the closure, then returns an exclusive reference to it.
See The _with
Method Suffix for a
discussion on the differences between the _with
suffixed methods and
those methods without it, their performance characteristics, and when
you might or might not choose a _with
suffixed method.
§Errors
Errors if reserving space for T
fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.try_alloc_with(|| "hello");
assert_eq!(x, Ok(&mut "hello"));
pub fn alloc_try_with<F, T, E>(&self, f: F) -> Result<&mut T, E>
pub fn alloc_try_with<F, T, E>(&self, f: F) -> Result<&mut T, E>
Pre-allocates space for a Result
in this Bump
, initializes it using
the closure, then returns an exclusive reference to its T
if Ok
.
Iff the allocation fails, the closure is not run.
Iff Err
, an allocator rewind is attempted and the E
instance is
moved out of the allocator to be consumed or dropped as normal.
See The _with
Method Suffix for a
discussion on the differences between the _with
suffixed methods and
those methods without it, their performance characteristics, and when
you might or might not choose a _with
suffixed method.
For caveats specific to fallible initialization, see
The _try_with
Method Suffix.
§Errors
Iff the allocation succeeds but f
fails, that error is forwarded by value.
§Panics
Panics if reserving space for Result<T, E>
fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.alloc_try_with(|| Ok("hello"))?;
assert_eq!(*x, "hello");
pub fn try_alloc_try_with<F, T, E>(
&self,
f: F,
) -> Result<&mut T, AllocOrInitError<E>>
pub fn try_alloc_try_with<F, T, E>( &self, f: F, ) -> Result<&mut T, AllocOrInitError<E>>
Tries to pre-allocates space for a Result
in this Bump
,
initializes it using the closure, then returns an exclusive reference
to its T
if all Ok
.
Iff the allocation fails, the closure is not run.
Iff the closure returns Err
, an allocator rewind is attempted and
the E
instance is moved out of the allocator to be consumed or dropped
as normal.
See The _with
Method Suffix for a
discussion on the differences between the _with
suffixed methods and
those methods without it, their performance characteristics, and when
you might or might not choose a _with
suffixed method.
For caveats specific to fallible initialization, see
The _try_with
Method Suffix.
§Errors
Errors with the Alloc
variant iff
reserving space for Result<T, E>
fails.
Iff the allocation succeeds but f
fails, that error is forwarded by
value inside the Init
variant.
§Example
let bump = bumpalo::Bump::new();
let x = bump.try_alloc_try_with(|| Ok("hello"))?;
assert_eq!(*x, "hello");
pub fn alloc_slice_copy<T>(&self, src: &[T]) -> &mut [T]where
T: Copy,
pub fn alloc_slice_copy<T>(&self, src: &[T]) -> &mut [T]where
T: Copy,
pub fn alloc_slice_clone<T>(&self, src: &[T]) -> &mut [T]where
T: Clone,
pub fn alloc_slice_clone<T>(&self, src: &[T]) -> &mut [T]where
T: Clone,
Clone
a slice into this Bump
and return an exclusive reference to
the clone. Prefer alloc_slice_copy
if T
is Copy
.
§Panics
Panics if reserving space for the slice fails.
§Example
#[derive(Clone, Debug, Eq, PartialEq)]
struct Sheep {
name: String,
}
let originals = [
Sheep { name: "Alice".into() },
Sheep { name: "Bob".into() },
Sheep { name: "Cathy".into() },
];
let bump = bumpalo::Bump::new();
let clones = bump.alloc_slice_clone(&originals);
assert_eq!(originals, clones);
pub fn alloc_slice_fill_with<T, F>(&self, len: usize, f: F) -> &mut [T]
pub fn alloc_slice_fill_with<T, F>(&self, len: usize, f: F) -> &mut [T]
Allocates a new slice of size len
into this Bump
and returns an
exclusive reference to the copy.
The elements of the slice are initialized using the supplied closure. The closure argument is the position in the slice.
§Panics
Panics if reserving space for the slice fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_with(5, |i| 5 * (i + 1));
assert_eq!(x, &[5, 10, 15, 20, 25]);
pub fn alloc_slice_fill_copy<T>(&self, len: usize, value: T) -> &mut [T]where
T: Copy,
pub fn alloc_slice_fill_copy<T>(&self, len: usize, value: T) -> &mut [T]where
T: Copy,
Allocates a new slice of size len
into this Bump
and returns an
exclusive reference to the copy.
All elements of the slice are initialized to value
.
§Panics
Panics if reserving space for the slice fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_copy(5, 42);
assert_eq!(x, &[42, 42, 42, 42, 42]);
pub fn alloc_slice_fill_clone<T>(&self, len: usize, value: &T) -> &mut [T]where
T: Clone,
pub fn alloc_slice_fill_clone<T>(&self, len: usize, value: &T) -> &mut [T]where
T: Clone,
Allocates a new slice of size len
slice into this Bump
and return an
exclusive reference to the copy.
All elements of the slice are initialized to value.clone()
.
§Panics
Panics if reserving space for the slice fails.
§Example
let bump = bumpalo::Bump::new();
let s: String = "Hello Bump!".to_string();
let x: &[String] = bump.alloc_slice_fill_clone(2, &s);
assert_eq!(x.len(), 2);
assert_eq!(&x[0], &s);
assert_eq!(&x[1], &s);
pub fn alloc_slice_fill_iter<T, I>(&self, iter: I) -> &mut [T]
pub fn alloc_slice_fill_iter<T, I>(&self, iter: I) -> &mut [T]
Allocates a new slice of size len
slice into this Bump
and return an
exclusive reference to the copy.
The elements are initialized using the supplied iterator.
§Panics
Panics if reserving space for the slice fails, or if the supplied iterator returns fewer elements than it promised.
§Example
let bump = bumpalo::Bump::new();
let x: &[i32] = bump.alloc_slice_fill_iter([2, 3, 5].iter().cloned().map(|i| i * i));
assert_eq!(x, [4, 9, 25]);
pub fn alloc_slice_fill_default<T>(&self, len: usize) -> &mut [T]where
T: Default,
pub fn alloc_slice_fill_default<T>(&self, len: usize) -> &mut [T]where
T: Default,
Allocates a new slice of size len
slice into this Bump
and return an
exclusive reference to the copy.
All elements of the slice are initialized to T::default()
.
§Panics
Panics if reserving space for the slice fails.
§Example
let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_default::<u32>(5);
assert_eq!(x, &[0, 0, 0, 0, 0]);
pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>
pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>
Allocate space for an object with the given Layout
.
The returned pointer points at uninitialized memory, and should be
initialized with
std::ptr::write
.
§Panics
Panics if reserving space matching layout
fails.
pub fn try_alloc_layout(&self, layout: Layout) -> Result<NonNull<u8>, AllocErr>
pub fn try_alloc_layout(&self, layout: Layout) -> Result<NonNull<u8>, AllocErr>
Attempts to allocate space for an object with the given Layout
or else returns
an Err
.
The returned pointer points at uninitialized memory, and should be
initialized with
std::ptr::write
.
§Errors
Errors if reserving space matching layout
fails.
pub fn chunk_capacity(&self) -> usize
pub fn chunk_capacity(&self) -> usize
Gets the remaining capacity in the current chunk (in bytes).
§Example
use bumpalo::Bump;
let bump = Bump::with_capacity(100);
let capacity = bump.chunk_capacity();
assert!(capacity >= 100);
pub fn iter_allocated_chunks(&mut self) -> ChunkIter<'_>
pub fn iter_allocated_chunks(&mut self) -> ChunkIter<'_>
Returns an iterator over each chunk of allocated memory that this arena has bump allocated into.
The chunks are returned ordered by allocation time, with the most recently allocated chunk being returned first, and the least recently allocated chunk being returned last.
The values inside each chunk are also ordered by allocation time, with the most recent allocation being earlier in the slice, and the least recent allocation being towards the end of the slice.
§Safety
Because this method takes &mut self
, we know that the bump arena
reference is unique and therefore there aren’t any active references to
any of the objects we’ve allocated in it either. This potential aliasing
of exclusive references is one common footgun for unsafe code that we
don’t need to worry about here.
However, there could be regions of uninitialized memory used as padding
between allocations, which is why this iterator has items of type
[MaybeUninit<u8>]
, instead of simply [u8]
.
The only way to guarantee that there is no padding between allocations or within allocated objects is if all of these properties hold:
- Every object allocated in this arena has the same alignment, and that alignment is at most 16.
- Every object’s size is a multiple of its alignment.
- None of the objects allocated in this arena contain any internal padding.
If you want to use this iter_allocated_chunks
method, it is your
responsibility to ensure that these properties hold before calling
MaybeUninit::assume_init
or otherwise reading the returned values.
Finally, you must also ensure that any values allocated into the bump
arena have not had their Drop
implementations called on them,
e.g. after dropping a [bumpalo::boxed::Box<T>
][crate::boxed::Box].
§Example
let mut bump = bumpalo::Bump::new();
// Allocate a bunch of `i32`s in this bump arena, potentially causing
// additional memory chunks to be reserved.
for i in 0..10000 {
bump.alloc(i);
}
// Iterate over each chunk we've bump allocated into. This is safe
// because we have only allocated `i32`s in this arena, which fulfills
// the above requirements.
for ch in bump.iter_allocated_chunks() {
println!("Used a chunk that is {} bytes long", ch.len());
println!("The first byte is {:?}", unsafe {
ch[0].assume_init()
});
}
// Within a chunk, allocations are ordered from most recent to least
// recent. If we allocated 'a', then 'b', then 'c', when we iterate
// through the chunk's data, we get them in the order 'c', then 'b',
// then 'a'.
bump.reset();
bump.alloc(b'a');
bump.alloc(b'b');
bump.alloc(b'c');
assert_eq!(bump.iter_allocated_chunks().count(), 1);
let chunk = bump.iter_allocated_chunks().nth(0).unwrap();
assert_eq!(chunk.len(), 3);
// Safe because we've only allocated `u8`s in this arena, which
// fulfills the above requirements.
unsafe {
assert_eq!(chunk[0].assume_init(), b'c');
assert_eq!(chunk[1].assume_init(), b'b');
assert_eq!(chunk[2].assume_init(), b'a');
}
pub unsafe fn iter_allocated_chunks_raw(&self) -> ChunkRawIter<'_>
pub unsafe fn iter_allocated_chunks_raw(&self) -> ChunkRawIter<'_>
Returns an iterator over raw pointers to chunks of allocated memory that this arena has bump allocated into.
This is an unsafe version of iter_allocated_chunks()
,
with the caller responsible for safe usage of the returned pointers as
well as ensuring that the iterator is not invalidated by new
allocations.
§Safety
Allocations from this arena must not be performed while the returned iterator is alive. If reading the chunk data (or casting to a reference) the caller must ensure that there exist no mutable references to previously allocated data.
In addition, all of the caveats when reading the chunk data from
iter_allocated_chunks()
still apply.
pub fn allocated_bytes(&self) -> usize
pub fn allocated_bytes(&self) -> usize
Calculates the number of bytes currently allocated across all chunks in this bump arena.
If you allocate types of different alignments or types with larger-than-typical alignment in the same arena, some padding bytes might get allocated in the bump arena. Note that those padding bytes will add to this method’s resulting sum, so you cannot rely on it only counting the sum of the sizes of the things you’ve allocated in the arena.
The allocated bytes do not include the size of bumpalo’s metadata, so the amount of memory requested from the Rust allocator is higher than the returned value.
§Example
let bump = bumpalo::Bump::new();
let _x = bump.alloc_slice_fill_default::<u32>(5);
let bytes = bump.allocated_bytes();
assert!(bytes >= core::mem::size_of::<u32>() * 5);
pub fn allocated_bytes_including_metadata(&self) -> usize
pub fn allocated_bytes_including_metadata(&self) -> usize
Calculates the number of bytes requested from the Rust allocator for this Bump
.
This number is equal to the allocated_bytes()
plus
the size of the bump metadata.