<a id="nupp.mem.pool"></a>
# `nupp.mem.pool`

A pool of record instances of one declared type.

An instance leaves the pool stamped with the declaration and carrying no
fields, and comes back cleared, so a hot path that would otherwise build a
table per event reuses the ones it already built.

```nupp
local pool = nupp.mem.pool

local record Damage
    amount: integer
    source: string
end

local damage = pool.new(Damage, 64)
local hit = damage:acquire()
hit.amount = 12
hit.source = "trap"
damage:release(hit) -- cleared, and kept for the next acquire
```

`capacity` is how many released instances the pool keeps; it is not a limit on
how many are out at once. An acquire past the free list allocates, and a
release onto a full free list lets the collector have the instance. Within
capacity, once the free list is warm, neither operation allocates.

Nothing here reaches C storage: the pool is ordinary tables, so it is available
on every backend. Struct rows are `nupp.mem.arena`.

## Constructors

<a id="nupp.mem.pool.new"></a>
### `pool.new` _constructor_

```nupp
function pool.new<T is table>(witness: Type<T>, capacity: integer?): pool.Pool<T>
```

Creates a pool of `witness` instances with `capacity` of them stamped and
waiting.

```nupp
local record Tick
    frame: integer
end

local ticks = pool.new(Tick, 8)
assert(ticks:free() == 8)
```

#### Type parameters

| Name | Description |
| --- | --- |
| `T` |  |

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `witness` | `Type\<T\>` | the record declaration, whose metatable stamps every instance |
| `capacity` | `integer?` | how many released instances to retain, 32 when omitted |

#### Returns

| Type | Description |
| --- | --- |
| `pool.Pool\<T\>` | the pool, warmed to capacity |

#### Raises

- when capacity is negative

## Types

<a id="nupp.mem.pool.Pool"></a>
### `Pool` _record_

```nupp
record pool.Pool<T is table>
    readonly capacity: integer
    acquire: function(exclusive self: Pool<T>): T
    release: function(exclusive self: Pool<T>, value: T): nil
    reserve: function(exclusive self: Pool<T>, count: integer): nil
    live: function(self: Pool<T>): integer
    free: function(self: Pool<T>): integer
    reset: function(exclusive self: Pool<T>): nil
end
```

A pool of instances stamped with one record declaration.

#### Type parameters

| Name | Description |
| --- | --- |
| `T` |  |

#### Methods

<a id="nupp.mem.pool.Pool.acquire"></a>
##### `acquire`

```nupp
acquire: function(exclusive self: Pool<T>): T
```

Hands out an instance, from the free list or freshly stamped.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Pool\<T\>` |  |

###### Returns

| Type | Description |
| --- | --- |
| `T` |  |

<a id="nupp.mem.pool.Pool.release"></a>
##### `release`

```nupp
release: function(exclusive self: Pool<T>, value: T): nil
```

Clears an instance and returns it to the free list.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Pool\<T\>` |  |
| `value` | `T` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

###### Raises

- when nothing is live, or value was not stamped by the pool's declaration

<a id="nupp.mem.pool.Pool.reserve"></a>
##### `reserve`

```nupp
reserve: function(exclusive self: Pool<T>, count: integer): nil
```

Stamps free instances until at least `count` are waiting.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Pool\<T\>` |  |
| `count` | `integer` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

###### Raises

- when count is negative

<a id="nupp.mem.pool.Pool.live"></a>
##### `live`

```nupp
live: function(self: Pool<T>): integer
```

How many instances are acquired and not yet released.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Pool\<T\>` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

<a id="nupp.mem.pool.Pool.free"></a>
##### `free`

```nupp
free: function(self: Pool<T>): integer
```

How many instances are waiting on the free list.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Pool\<T\>` |  |

###### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

<a id="nupp.mem.pool.Pool.reset"></a>
##### `reset`

```nupp
reset: function(exclusive self: Pool<T>): nil
```

Drops the free list.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Pool\<T\>` |  |

###### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

###### Raises

- when any instance is live

#### Fields

<a id="nupp.mem.pool.Pool.capacity"></a>
##### `capacity`

```nupp
capacity: integer
```

How many released instances the pool retains for reuse.