# Arenas

> UForm for Mojo

Every output whose length only the call knows, embeddings, states, token vectors and probabilities, lands in an `Arena` you pass, and the verb answers a view over it without copying.
`Arena(executor)` places it where that executor computes, decided once, and `Arena(library)` makes host pages for the calling thread.
Each call rewinds its arena, so the previous call's views die and a steady loop allocates once; reading a stale one raises `Status.INVALID_ARGUMENT`.
To keep a result past the next call, pass that call another arena, and give every deferred call its own.
An arena from a VRAM executor holds device memory, which host accessors refuse with `Status.DEVICE`, and serves only that executor's calls, keeping the executor alive until the arena goes.

The engine classifies every input pointer through the driver, so `TapeView.of` takes a host span or a host or device pointer, such as `buffer.unsafe_ptr()` of a MAX `DeviceBuffer`, with its offsets in host memory.

`from uform import ArenaDescription, Arena`

## ArenaDescription

`uform_arena_description_t`: where an arena's outputs live.

```mojo
struct ArenaDescription
```

- `residency` `Residency`: [`RAM`](https://www.unum.cloud/docs/uform/mojo/models.md#RAM) for host pages, [`VRAM`](https://www.unum.cloud/docs/uform/mojo/models.md#VRAM) for one device's memory.
- `device` `Int32`: The device ordinal, as [`Executor.for_vram`](https://www.unum.cloud/docs/uform/mojo/executors.md#for_vram) takes it, or -1 for host pages.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## Arena

The memory every output whose length scales with a call lands in, freed when it goes out of scope.

```mojo
struct Arena
```

Made where an executor computes, host pages or the memory of its GPU, decided once; nothing is
allocated until a call writes into it. Every call handed it rewinds and refills it, which
invalidates the previous call's outputs, so a steady loop allocates once. One arena serves one
call at a time; a second concurrent use is refused by the engine as [`CONTENDED`](https://www.unum.cloud/docs/uform/mojo/errors.md#CONTENDED), which leaves
the holder's results readable.

A result refuses every read with [`INVALID_ARGUMENT`](https://www.unum.cloud/docs/uform/mojo/errors.md#INVALID_ARGUMENT) once a later call rewinds its arena, and a
result over a device arena refuses every host read with [`DEVICE`](https://www.unum.cloud/docs/uform/mojo/errors.md#DEVICE). A device arena serves only
calls on the executor that made it, and keeps that executor alive until it is freed.

Conforms to: `Deinitable`, `Movable`

## __init__

Host pages for calls on the calling thread. Calls `uform_arena_init`.

```mojo
def __init__(out self, library: Library)
```

```mojo
def __init__(out self, executor: Executor)
```

Memory where `executor` computes, serving the calls of its residency. Calls `uform_arena_init`.

- `executor`: The executor whose calls it serves; host pages may outlive it, and a device arena keeps it alive.

## __deinit__

Frees the arena and every output in it, then lets a device arena's executor go. Calls `uform_arena_free`.

```mojo
def __deinit__(deinit self)
```

The executor and the loader reference are surrendered only after the call, for the reason
`_ExecutorHandle` records.

## describe

Where its outputs live, as the executor that made it decided. Calls `uform_arena_describe`.

```mojo
def describe(self) -> ArenaDescription
```