farena 0.1.0

A file-backed arena allocator using pread for RSS-conscious byte storage
Documentation 
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

# farena

File-backed arena allocator using `pread(2)` for RSS-conscious byte storage.

## Usage

```rust
use farena::{FileArena, FileArenaWriter, Location};

// Write phase
let mut writer = FileArenaWriter::new()?;
let (offset1, len1) = writer.push("hello")?;
let (offset2, len2) = writer.push(" world")?;
let file = writer.finish()?.unwrap();

// Read phase
let arena = FileArena::new(vec![file])?;
let loc1 = Location::new(0, offset1, len1);
let loc2 = Location::new(0, offset2, len2);

assert_eq!(arena.get(loc1)?, b"hello");
assert_eq!(arena.get(loc2)?, b" world");
```

### Multiple files

```rust
let mut w1 = FileArenaWriter::new()?;
let (o1, l1) = w1.push("data1")?;
let f1 = w1.finish()?.unwrap();

let mut w2 = FileArenaWriter::new()?;
let (o2, l2) = w2.push("data2")?;
let f2 = w2.finish()?.unwrap();

let arena = FileArena::new(vec![f1, f2])?;
let loc1 = Location::new(0, o1, l1);  // file index 0
let loc2 = Location::new(1, o2, l2);  // file index 1
```

### Buffer reuse

```rust
let mut buf = Vec::new();
arena.get_into(loc1, &mut buf)?;  // appends to buf
```

## API

| Method | Description |
|--------|-------------|
| `FileArenaWriter::new()` | Create writer backed by temp file |
| `writer.push(data)` | Append data, returns `(offset, len)` |
| `writer.finish()` | Flush and return file handle |
| `FileArena::new(files)` | Create arena from file handles |
| `arena.get(loc)` | Read bytes at location |
| `arena.get_into(loc, buf)` | Read bytes into buffer |