# orca.pool_config

> A module of morca's API.

Worker pools orca grows and shrinks itself (#267): a `[pools.<name>]` table in orca.toml, read and checked here, recorded by `orca register` in `orca.pools`, and acted on by the scheduler (`orca.pool_scale`).

[pools.lab]
    provider = "hetzner"
    machines = [
      { type = "cax31", wait = 600 },   # prefer this; keep trying it 10 min
      { type = "cax21", wait = 600 },
      { type = "cpx32" },               # the last: no wait, keep trying it
    ]
    locations = ["hel1", "nbg1", "fsn1"]
    max_machines = 3
    idle_seconds = 900

A pipeline runs on the pool with `placement = "worker:lab"`, as on a pool of
workers started by hand. `machines` is the order of preference: orca tries
the first type in each location in turn, retries it until its `wait`
(seconds) has passed since it started trying, then moves to the next. The
last type has no `wait`: orca keeps trying it. A machine that's running is
never replaced by a type higher in the list.

## Structs

### `MachineChoice`

```mojo
struct MachineChoice
```

One entry of a pool's `machines`: a provider's machine type, and how long to keep trying it before the next (`NO_WAIT` for the last).

Implements: `Copyable`, `Movable`

Fields:

- `type: String`
- `wait: Int`

### `PoolConfig`

```mojo
struct PoolConfig
```

A `[pools.<name>]` table, checked.

Implements: `Copyable`, `Movable`

Fields:

- `name: String`
- `provider: String`
- `machines: List[MachineChoice]`
- `locations: List[String]`
- `max_machines: Int`
- `idle_seconds: Int`

#### `machines_json`

```mojo
def machines_json(self) -> String
```

`machines` as orca.pools keeps it: `[{"type": .., "wait": ..}]`, `wait` left out for none.

#### `locations_json`

```mojo
def locations_json(self) -> String
```

## Functions

### `read_pool`

```mojo
def read_pool(doc: TomlDoc, name: String) -> PoolConfig
```

`[pools.<name>]` of `doc`, checked; raises `<line>: [pools.<name>] <why>`.

### `read_pools`

```mojo
def read_pools(doc: TomlDoc) -> List[PoolConfig]
```

Every `[pools.<name>]` of `doc`, checked, in the file's order.

### `record_pools`

```mojo
def record_pools(mut db: State, pools: List[PoolConfig]) -> List[String]
```

Makes `orca.pools` what orca.toml says, `pools`: each upserted, and a pool the file no longer has deleted, so the scheduler stops adding machines to it and removes the ones it has once idle. The pools deleted.

## Aliases

### `PROVIDERS`

```mojo
comptime PROVIDERS = Array[__literal_size__=Int(2)](String("hetzner"), String("ec2"), __list_literal__=NoneType(None))
```

### `POOL_KEYS`

```mojo
comptime POOL_KEYS = Array[__literal_size__=Int(5)](String("provider"), String("machines"), String("locations"), String("max_machines"), String("idle_seconds"), __list_literal__=NoneType(None))
```

### `DEFAULT_MAX_MACHINES`

```mojo
comptime DEFAULT_MAX_MACHINES = 1
```

### `DEFAULT_IDLE_SECONDS`

```mojo
comptime DEFAULT_IDLE_SECONDS = 900
```

### `MAX_MACHINES`

```mojo
comptime MAX_MACHINES = 100
```

### `NO_WAIT`

```mojo
comptime NO_WAIT = -1
```

A machine type's `wait` when it has none: keep trying it.