README.md
1# `bumpalo`
2
3
4**A fast bump allocation arena for Rust.**
5
6[](https://docs.rs/bumpalo/)
7[](https://crates.io/crates/bumpalo)
8[](https://crates.io/crates/bumpalo)
9[](https://dev.azure.com/fitzgen/bumpalo/_build/latest?definitionId=2&branchName=master)
10
11
12
13### Bump Allocation
14
15Bump allocation is a fast, but limited approach to allocation. We have a chunk
16of memory, and we maintain a pointer within that memory. Whenever we allocate an
17object, we do a quick test that we have enough capacity left in our chunk to
18allocate the object and then increment the pointer by the object's size. *That's
19it!*
20
21The disadvantage of bump allocation is that there is no general way to
22deallocate individual objects or reclaim the memory region for a
23no-longer-in-use object.
24
25These trade offs make bump allocation well-suited for *phase-oriented*
26allocations. That is, a group of objects that will all be allocated during the
27same program phase, used, and then can all be deallocated together as a group.
28
29### Deallocation en Masse, but No `Drop`
30
31To deallocate all the objects in the arena at once, we can simply reset the bump
32pointer back to the start of the arena's memory chunk. This makes mass
33deallocation *extremely* fast, but allocated objects' `Drop` implementations are
34not invoked.
35
36### What happens when the memory chunk is full?
37
38This implementation will allocate a new memory chunk from the global allocator
39and then start bump allocating into this new memory chunk.
40
41### Example
42
43```rust
44use bumpalo::Bump;
45use std::u64;
46
47struct Doggo {
48 cuteness: u64,
49 age: u8,
50 scritches_required: bool,
51}
52
53// Create a new arena to bump allocate into.
54let bump = Bump::new();
55
56// Allocate values into the arena.
57let scooter = bump.alloc(Doggo {
58 cuteness: u64::max_value(),
59 age: 8,
60 scritches_required: true,
61});
62
63assert!(scooter.scritches_required);
64```
65
66### Collections
67
68When the on-by-default `"collections"` feature is enabled, a fork of some of the
69`std` library's collections are available in the `collections` module. These
70collection types are modified to allocate their space inside `bumpalo::Bump`
71arenas.
72
73```rust
74use bumpalo::{Bump, collections::Vec};
75
76// Create a new bump arena.
77let bump = Bump::new();
78
79// Create a vector of integers whose storage is backed by the bump arena. The
80// vector cannot outlive its backing arena, and this property is enforced with
81// Rust's lifetime rules.
82let mut v = Vec::new_in(&bump);
83
84// Push a bunch of integers onto `v`!
85for i in 0..100 {
86 v.push(i);
87}
88```
89
90Eventually [all `std` collection types will be parameterized by an
91allocator](https://github.com/rust-lang/rust/issues/42774) and we can remove
92this `collections` module and use the `std` versions.
93
94### `#![no_std]` Support
95
96Requires the `alloc` nightly feature. Disable the on-by-default `"std"` feature:
97
98```toml
99[dependencies.bumpalo]
100version = "1"
101default-features = false
102```
103
104
README.tpl
1# `{{crate}}`
2
3{{readme}}
4
){kind=link}
){kind=link}
){kind=link}
){kind=link}