[−][src]Crate compact_arena
A crate with a few single-typed arenas that work exclusively with indexes. The indexes are sized with the arena. This can reduce memory footprint when changing pointers to indices e.g. on 64-bit systems.
The arenas use a variant of "branded indices": The indices contain a type
tag that binds them to their respective arena so you cannot mix up two
arenas by accident. Unlike the indexing
crate, this implements the type tags as actual unique types. This has the
downside of not being able to Sync
or Send
arenas or indices, but on the
other hand, we can store indices within objects that we put into the arena,
which is a boon to things like graph data structures.
Use the mk_arena!
to create an arena, then add
items to it and index it
with arena[idx]
.
Examples
mk_nano_arena!(arena); let idx = arena.add(1usize); assert_eq!(1, arena[idx]);
You can work with multiple arenas:
mk_nano_arena!(a); mk_nano_arena!(b); ..
The compiler gives you a type error if you mix up arenas:
mk_nano_arena!(a); mk_nano_arena!(b); let i = a.add(1usize); let _ = b[i];
The indices should not be able to escape the block with the mk_*arena
call
let idx = { mk_tiny_arena!(arena, 1); arena.add(1usize)) }; assert!(core::mem::size_of_val(&a) == 4);
Also, arenas may not be instantiated recursively:
# use compact_arena::{mk_nano_arena, Idx8};
fn recursive(idx: Option<Idx32<'_>>) {
mk_nano_arena!(arena, 2); // `tag` does not live long enough
if let Some(idx) = idx {
assert_eq!("hello", arena[idx]);
} else {
recursive(Some(arena.add("hello")));
}
}
recursive(None);
Macros
in_arena | Run a piece of code inside an arena |
in_nano_arena | Run code using a nano arena. The indirection through the macro is required to bind the indices to the arena. |
in_tiny_arena | Run code using a tiny arena. The indirection through this macro is required to bind the indices to the arena. |
mk_arena | Run code using an arena. The indirection through the macro is required
to safely bind the indices to the arena. The macro takes an identifier that
will be bound to the |
mk_nano_arena | Create a tiny arena. The indirection through this macro is required to bind the indices to the arena. |
mk_tiny_arena | Create a tiny arena. The indirection through this macro is required to bind the indices to the arena. |
Structs
CapacityExceeded | An error type that gets returned on trying to add an element to an already full arena. It contains the element so you can reuse it |
Idx | An index into the arena. You will not directly use this type, but one of
the aliases this crate provides ( |
NanoArena | A "nano" arena containing up to 256 elements. This variant only works
with types implementing |
SmallArena | A "Small" arena based on a resizable slice (i.e. a |
TinyArena | A "tiny" arena containing <64K elements. This variant only works with
types implementing |
Type Definitions
Idx8 | The index type for a nano arena is 8 bits large. You will usually get the
index from the arena and use it by indexing, e.g. |
Idx16 | The index type for a tiny arena is 16 bits large. You will usually get the
index from the arena and use it by indexing, e.g. |
Idx32 | The index type for a small arena is 32 bits large. You will usually get the
index from the arena and use it by indexing, e.g. |