lib/bumpalo/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! An allocator that hands out memory by moving one cursor and releases every
 2 //! allocation at once is a *bump arena*. A caller reaches for it when many
 3 //! small objects share one lifetime. The arena takes its memory from an
 4 //! allocator the caller supplies, the *backing allocator*.
 5 //!
 6 //! The arena holds its memory in a contiguous block it owns, a *chunk*. Each
 7 //! chunk holds its own header, its capacity, and the offset that separates
 8 //! handed-out bytes from free bytes, the *cursor*. Each chunk points at the
 9 //! chunk before it, so the arena is a chain of chunks with the newest at the
10 //! head. An allocation inside the active chunk moves the cursor by the
11 //! requested size and returns those bytes, and the arena stores no header of
12 //! its own beside the object. When the active chunk has too little room, the
13 //! arena asks the backing allocator for a new chunk, usually twice the size of
14 //! the last one, and makes it the active one.
15 //!
16 //! A caller can set an optional cap on the bytes the arena may take from the
17 //! backing allocator, the *backing data capacity limit*. A request larger than
18 //! the remaining cap fails, which leaves the arena the size it was.
19 //! `initBuffer` takes a buffer from the caller and links it as a chunk the
20 //! arena borrows, the *caller storage*, and the arena still grows through the
21 //! backing allocator once that buffer fills.
22 //!
23 //! `reset` releases every allocation at once. Which chunks a `reset` call keeps
24 //! depends on the *reset mode*: `free_all`, `retain_current`,
25 //! `retain_capacity`, or `retain_with_limit`. `reset` answers false when a
26 //! retaining mode cannot keep the capacity it was asked for, which happens when
27 //! a lowered backing data capacity limit cannot cover a replacement chunk.
28 //! Every pointer into the arena is dead after a reset, and the arena runs no
29 //! cleanup code for the objects that lived there, so the caller finishes with
30 //! those pointers first.
31 
32 const bump_impl = @import("bump.zig");
33 
34 pub const Bump = bump_impl.Bump;
35 pub const BumpAllocator = bump_impl.BumpAllocator;
36 pub const chunk_alignment = bump_impl.chunk_alignment;
37 pub const default_min_alignment = bump_impl.default_min_alignment;
38 pub const first_allocation_goal = bump_impl.first_allocation_goal;
39 pub const malloc_overhead = bump_impl.malloc_overhead;
40 pub const typical_page_size = bump_impl.typical_page_size;