# Arenas

> UForm for JavaScript

Every output whose length scales with the call lands in an arena, and the verb answers views into it rather than copies.
Each call rewinds the arena it is given, detaching the buffers under the previous call's views, so a stale view refuses its reads with `invalid-argument` instead of reading another call's memory.
To keep one result past the next call, give that call another arena.
A deferred call holds its arena until final, and a second call naming it finishes `contended`.

```javascript
const first = model.textEncode(["first"], arena);
const second = model.textEncode(["second"], arena);
first.embeddings.data; // throws: the arena was rewound
```

`import { Arena } from 'uform';`

`import { ArenaView } from 'uform';`

## Arena

Memory the library writes every output whose length scales with a call into, reused across calls.

```typescript
class Arena implements Disposable
```

Every verb with such an output takes one and answers a view into it rather than a copy, so a
steady loop allocates once. Each call rewinds the arena it is handed and detaches every buffer
over the previous call's outputs: a view refuses its reads with [`Status.InvalidArgument`](https://www.unum.cloud/docs/uform/javascript/errors.md#InvalidArgument)
from then on. To keep one result past the next call, give that call another arena. A deferred
call holds it until final: another call naming it before then finishes [`Status.Contended`](https://www.unum.cloud/docs/uform/javascript/errors.md#Contended)
and leaves the first call's outputs alone, and [`free`](https://www.unum.cloud/docs/uform/javascript/training.md#free) waits for it.

## Arena

Makes an arena where [`executor`](https://www.unum.cloud/docs/uform/javascript/models.md#executor) computes, or host pages for calls on the calling thread.

```typescript
new Arena(executor?: Executor)
```

Calls `uform_arena_init`.

## free

Releases the memory now, once every deferred call writing it is final, detaching every view into it.

```typescript
free(): void
```

Calls `uform_arena_free`.

## compiled

The backend handle every verb is handed.

```typescript
readonly compiled: CompiledArena
```

## residency

`"ram"` or `"vram"`, where the executor that made it computes; a VRAM arena's views refuse host reads.

```typescript
readonly residency: string
```

## ArenaView

Outputs a call wrote into an arena, readable until the arena's next call rewinds it.

```typescript
abstract class ArenaView
```

The rewind detaches the buffer under every array, so each accessor refuses once the arena moved
on, and refuses device memory with [`Status.Device`](https://www.unum.cloud/docs/uform/javascript/errors.md#Device), so a view never reads memory its call
did not write.