# gizlang/arena

A region of raw memory that the host hands over, used as a stack: a block is taken from its end, and rewinding to a point taken before it gives it back. The graphics modules take their memory from an arena, so none of them calls the operating system: the host maps the region, reads its files into it and keeps it mapped.

```gizlang
import * as Arena from "gizlang/arena";
```

## Types

### `Arena`

```gizlang
type Arena = { at: i64; size: i64; used: i64; }
```

The region of SIZE bytes at AT, with USED bytes taken from its start.

- `at`: `i64`
- `size`: `i64`
- `used`: `i64`

## Functions

### `arena`

```gizlang
function arena(at: i64, size: i64): Arena
```

The arena over SIZE bytes of writable raw memory at AT. The memory must stay mapped while the arena is used.

### `footprint`

```gizlang
function footprint(bytes: i64): i64
```

The room a block of BYTES takes in an arena: BYTES rounded up to 8, as take rounds it. A host sizes an arena with it.

Effects: fail.

### `take`

```gizlang
function take(a: mut Arena, bytes: i64): i64
```

A block of BYTES, rounded up to 8, taken from the end of A. The block holds whatever the memory held: a user writes it
before it reads it, or clears it (the host's fresh pages are already zero, and clearing them here would touch them all).
The arena must have room: a block that does not fit is a sizing error in the host, so the program stops rather than
writing past the region.

Effects: fail.

### `rewind`

```gizlang
function rewind(a: mut Arena, point: i64): void
```

Give back every block taken after POINT, a value of `used` read before them.

