backpressure

Async runtime boundaries for cancellation and backpressure-aware adapters.

Types

AdapterMode

Adapter mode used for async runtime scheduling.

pub type AdapterMode {
  PushPull
  PushOnly
  PullOnly
}

Constructors

```
PushPull
```
```
PushOnly
```
```
PullOnly
```

Boundary

Runtime boundary contract for async scheduling.

pub type Boundary {
  Boundary(
    mode: AdapterMode,
    max_in_flight: Int,
    max_queued: Int,
    cancellation_budget_ms: Int,
  )
}

Constructors

Boundary(
  mode: AdapterMode,
  max_in_flight: Int,
  max_queued: Int,
  cancellation_budget_ms: Int,
)

Runtime

opaque

Async runtime state with explicit backpressure limits.

pub opaque type Runtime

RuntimeError

Task transition errors.

pub type RuntimeError {
  DuplicateTask(key: String)
  QueueSaturated(key: String, max_queued: Int)
  UnknownTask(key: String)
  InvalidTransition(key: String, state: String, action: String)
}

Constructors

```
DuplicateTask(key: String)
```

QueueSaturated(key: String, max_queued: Int)

```
UnknownTask(key: String)
```

InvalidTransition(key: String, state: String, action: String)

TaskState

Lifecycle state of one async task.

pub type TaskState {
  Queued(seq: Int)
  InFlight(seq: Int, started_ms: Int)
  Succeeded(seq: Int)
  Failed(seq: Int, reason: String)
  Cancelled(seq: Int, reason: String)
}

Constructors

```
Queued(seq: Int)
```
```
InFlight(seq: Int, started_ms: Int)
```
```
Succeeded(seq: Int)
```
```
Failed(seq: Int, reason: String)
```
```
Cancelled(seq: Int, reason: String)
```

Values

boundary

pub fn boundary(
  mode: AdapterMode,
  max_in_flight: Int,
  max_queued: Int,
  cancellation_budget_ms: Int,
) -> Boundary

Build a boundary profile.

cancel

pub fn cancel(
  runtime: Runtime,
  key: String,
  reason: String,
) -> #(Runtime, Result(Nil, RuntimeError))

Cancel one queued or in-flight task.

default_boundary

pub fn default_boundary() -> Boundary

Default boundary profile for mixed push/pull adapters.

enqueue

pub fn enqueue(
  runtime: Runtime,
  key: String,
) -> #(Runtime, Result(Nil, RuntimeError))

Enqueue one task with backpressure checks.

error_label

pub fn error_label(error: RuntimeError) -> String

Stable runtime-error label.

fail

pub fn fail(
  runtime: Runtime,
  key: String,
  reason: String,
) -> #(Runtime, Result(Nil, RuntimeError))

Mark one in-flight task as failed.

in_flight_count

pub fn in_flight_count(runtime: Runtime) -> Int

In-flight task count.

mode_label

pub fn mode_label(mode: AdapterMode) -> String

Stable adapter mode label.

new

pub fn new(boundary: Boundary) -> Runtime

Build a runtime.

queued_count

pub fn queued_count(runtime: Runtime) -> Int

Queued task count.

retry

pub fn retry(
  runtime: Runtime,
  key: String,
) -> #(Runtime, Result(Nil, RuntimeError))

Retry a failed/cancelled task by putting it back in queue.

runtime_boundary

pub fn runtime_boundary(runtime: Runtime) -> Boundary

Boundary accessor.

signature

pub fn signature(runtime: Runtime) -> String

Stable runtime signature for deterministic fixtures.

start_available

pub fn start_available(
  runtime: Runtime,
  now_ms: Int,
) -> #(Runtime, List(String))

Start queued tasks up to in-flight limit.

state

pub fn state(
  runtime: Runtime,
  key: String,
) -> option.Option(TaskState)

Lookup task state by key.

state_label

pub fn state_label(state: TaskState) -> String

Stable task-state label.

succeed

pub fn succeed(
  runtime: Runtime,
  key: String,
) -> #(Runtime, Result(Nil, RuntimeError))

Mark one in-flight task as succeeded.

tasks

pub fn tasks(runtime: Runtime) -> List(TaskState)

Tasks in stable sequence order.

valid

pub fn valid(runtime: Runtime) -> Bool

Validate boundary settings.