# Arena allocator

Scratchpads [doc/mem/scratch] are fine for temporary data, but for
semi-temporary data, not so much. Sometimes, we need to hold onto temporary data
for longer and the size of that data can vary wildly, making it difficult to
find a reasonable size for our buffer.

If we have a clear point where we can say "from this moment, I don't need any of
this class of data", then the Arena allocator [doc/mem/alloc] is ideally suited
for the task.

One such example are line buffers in text/ed. We don'y know beforehand how many
characters we'll have to deal with, it depends on the size of the input file.
Also, we don't know if the user is going to edit the file a little bit or a lot.
Allocating a static buffer either wastes memory or makes the app too
constrained.

The Arena allocator is a linked list of fixed size buffers (4 kilobytes) that
grow whenever we need more memory, by adding a buffer to the linked list. When
we clear the arena, it rewinds itself to its first buffer and reuse those
previously allocated buffers for subsequent allocations, growing the list again
if it reaches its previous limit.

## Arena API

The Arena lives at mem/arena.fs and extends Allocator and adds:

:new ( -- arena )
  create a new empty Arena.

:usedsz ( arena -- sz )
  number of bytes used in the buffer so far.

:reset ( arena -- )
  empty the buffer and resets its pointers. Previously created buffers stay
  there, but their memory is reclaimed and can be used again.

:reserve ( arena -- )
  Ensure that "next" buffer exist, that is, ensure that we can allocate at least
  ARENASZ bytes without allocating anything from the system.

There is also the global ARENASZ const which is $1000.

## C API

Arena API can be exposed to C by loading mem/arena.h, which add these
functions:

int arena_new();              --> :new
void arena_reset(int self);   --> :reset
void arena_reserve(int self); --> :reserve
