File: README.md

package info (click to toggle)
rust-typed-arena 2.0.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 140 kB
  • sloc: sh: 8; makefile: 2
file content (71 lines) | stat: -rw-r--r-- 2,347 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# `typed-arena`

[![](https://docs.rs/typed-arena/badge.svg)](https://docs.rs/typed-arena/)
[![](https://img.shields.io/crates/v/typed-arena.svg)](https://crates.io/crates/typed-arena)
[![](https://img.shields.io/crates/d/typed-arena.svg)](https://crates.io/crates/typed-arena)
[![Travis CI Build Status](https://travis-ci.org/SimonSapin/rust-typed-arena.svg?branch=master)](https://travis-ci.org/SimonSapin/typed-arena)

**A fast (but limited) allocation arena for values of a single type.**

Allocated objects are destroyed all at once, when the arena itself is destroyed.
There is no deallocation of individual objects while the arena itself is still
alive. The flipside is that allocation is fast: typically just a vector push.

There is also a method `into_vec()` to recover ownership of allocated objects
when the arena is no longer required, instead of destroying everything.

## Example

```rust
use typed_arena::Arena;

struct Monster {
    level: u32,
}

let monsters = Arena::new();

let vegeta = monsters.alloc(Monster { level: 9001 });
assert!(vegeta.level > 9000);
```

## Safe Cycles

All allocated objects get the same lifetime, so you can safely create cycles
between them. This can be useful for certain data structures, such as graphs
and trees with parent pointers.

```rust
use std::cell::Cell;
use typed_arena::Arena;

struct CycleParticipant<'a> {
    other: Cell<Option<&'a CycleParticipant<'a>>>,
}

let arena = Arena::new();

let a = arena.alloc(CycleParticipant { other: Cell::new(None) });
let b = arena.alloc(CycleParticipant { other: Cell::new(None) });

a.other.set(Some(b));
b.other.set(Some(a));
```

## Alternatives

### Need to allocate many different types of values?

Use multiple arenas if you have only a couple different types or try
[`bumpalo`](https://crates.io/crates/bumpalo), which is a bump-allocation arena
can allocate heterogenous types of values.

### Want allocation to return identifiers instead of references and dealing with references and lifetimes everywhere?

Check out [`id-arena`](https://crates.io/crates/id-arena) or
[`generational-arena`](https://crates.io/crates/generational-arena).

### Need to deallocate individual objects at a time?

Check out [`generational-arena`](https://crates.io/crates/generational-arena)
for an arena-style crate or look for a more traditional allocator.