# orca.admission

> A module of morca's API.

Admission by memory pressure, where it shows (#202): each host's newest reading in `orca.pressure`, for Ops › Control, `/api/workers`, `/metrics`, `orca status` and the home and runs pages, and the alert when a hold has nothing of orca's to wait for.

The scheduler records its own host (`scheduler`) every few seconds and on
each change of hold; the UI records a worker's (`worker:<token id>`) from
each claim, where the worker sends its `Report`. The decision itself is
`orca.pressure.Admission`'s, made where the runs start: the scheduler for
the local runner and the control host, each worker for the runs it claims.

A row older than `FRESH_SECONDS` is shown as no reading: a scheduler or
worker that stopped isn't holding anything.

## Structs

### `Report`

```mojo
struct Report
```

A host's reading and whether it holds starts, as recorded and sent.

Implements: `Copyable`, `Movable`

Fields:

- `kind: String`: `orca.pressure.Source.kind`; empty for no PSI here.
- `path: String`
- `has: Bool`: Whether there is a reading.
- `some10: Float64`
- `some60: Float64`
- `some300: Float64`
- `full10: Float64`
- `full60: Float64`
- `full300: Float64`
- `limit: Float64`: `ORCA_ADMIT_MEMORY_PRESSURE`; 0 for off.
- `held: String`: The reason runs wait (`waiting: memory pressure ...`), or empty.
- `held_seconds: Float64`
- `stuck: Bool`: Held past its grace with nothing of orca's going: one at a time starts (`Admission.escape`).

#### `of`

```mojo
def of(s: Source, a: Admission, now: Float64) -> Self
```

What `a`, reading `s`, says at `now` (its clock).

#### `json`

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

#### `from_json`

```mojo
def from_json(v: Value) -> Self
```

### `PressureRow`

```mojo
struct PressureRow
```

Implements: `Copyable`, `Movable`

Fields:

- `host: String`
- `report: Report`
- `age: Int`: Seconds since it was recorded.

#### `fresh`

```mojo
def fresh(self) -> Bool
```

## Functions

### `worker_host`

```mojo
def worker_host(token_id: Int) -> String
```

### `record`

```mojo
def record(mut db: State, host: String, r: Report)
```

Keeps `host`'s newest reading.

### `alert_stuck`

```mojo
def alert_stuck(mut db: State, subject: String, r: Report)
```

'memory-pressure': `subject` has held starts past its grace with nothing of orca's running, so its pressure is someone else's; runs now start there one at a time.

### `resolve_stuck`

```mojo
def resolve_stuck(mut db: State, subject: String, r: Report)
```

Ends `alert_stuck`'s alert once `subject` no longer holds.

### `pressure_rows`

```mojo
def pressure_rows(mut db: State, host: String = "") -> List[PressureRow]
```

Every host's newest reading, or `host`'s alone, the scheduler's first.

### `scheduler_pressure`

```mojo
def scheduler_pressure(mut db: State) -> Optional[PressureRow]
```

The scheduler's host's reading, if one is fresh.

### `row_json`

```mojo
def row_json(row: Optional[PressureRow]) -> String
```

A reading as JSON (`Report.json`, with `host` and `age_seconds`), or null with none fresh.

### `state_text`

```mojo
def state_text(r: Report) -> String
```

What the host does about its pressure, in words.

### `held_warning`

```mojo
def held_warning(row: Optional[PressureRow]) -> String
```

The home and runs pages' line while the scheduler's host holds starts, or empty.

### `pressure_html`

```mojo
def pressure_html(mut h: Html, row: Optional[PressureRow])
```

Ops › Control's Memory pressure card.

### `pressure_prometheus`

```mojo
def pressure_prometheus(rows: List[PressureRow]) -> String
```

`/metrics`' gauges, a series per host with a fresh reading.

## Aliases

### `SCHEDULER_HOST`

```mojo
comptime SCHEDULER_HOST = "scheduler"
```

`orca.pressure.host` of the scheduler's own host.

### `FRESH_SECONDS`

```mojo
comptime FRESH_SECONDS = 60
```

### `ALERT_KIND`

```mojo
comptime ALERT_KIND = "memory-pressure"
```