Bosatsu packages

Yichus/Steps

Builtin package (resource steps.bosatsu). This is the complete package source used by this build. The export list names its public API; definitions below give the types and behavior.

New to the API? Start with Make a data app or Build an API, then use this page to look up a definition.

package Yichus/Steps

from Bosatsu/Predef import List
from Yichus/IO import IO, pure, flat_map, fold_until
from Yichus/Transaction import Txn, tx_pure, tx_bind, tx_abort, tx_fold_until
from Zafu/Control/IterState import IterState, Continue, Done

export (
  Next(), Steps(), Performed(), Answer(), Carry(), Worked(), Ran(),
  run_in_worker, tx_run_stored
)

exposes (Yichus/IO, Yichus/Transaction)

# What a step program needs next: a request performed for it, or its value.
enum Next[r, a]:
  Asks(request: r)
  Reached(value: a)

# The whole flow of one asynchronous computation. `next` reads what the
# program needs from its state, and `heard` is its state once a request has
# its reply. Neither performs anything, so the flow reads the same whichever
# way it is run.
struct Steps[c, r, p, a](next: c -> Next[r, a], heard: (c, r, p) -> c)

# A request performed in the worker running the computation: its reply, or
# why the computation stops.
enum Performed[p, e]:
  Replied(reply: p)
  Failed(reason: e)

# A request answered for a stored computation: its reply, or the request is
# handed to another worker and the computation waits for it with its state
# saved, or why the computation stops.
enum Answer[p, e]:
  Recalled(reply: p)
  Handed
  Declined(reason: e)

# The developer's choice for one asynchronous computation, written as a
# constant beside it and matched where the computation runs, so both sides
# stay written and checked and changing the constant is the whole change.
#
# InWorker is the traditional model (run_in_worker). The worker that
# starts the computation performs every request itself with the logic its
# own deploy shipped, and the state stays in that worker's memory, so
# nothing is written between requests. A worker that stops (a deploy, a
# crash, a scale-down) loses the computation, which starts again from its
# start state and performs its requests again.
#
# Stored (tx_run_stored) carries the computation on inside one transaction
# from the state the store holds, saves every reply before the next
# request, and hands a request it cannot answer to another worker. The
# store always holds the state the computation carries on from, so any
# engine on any deploy picks it up where it was, and no request whose reply
# was saved is performed again. It pays for that by reading and writing the
# state at every step.
enum Carry:
  InWorker
  Stored

# How a run in the worker ended: the program's value with the state that
# reached it; or stopped for a reason; or the bound ran out first.
enum Worked[c, a, e]:
  WorkedTo(state: c, value: a)
  WorkedStopped(reason: e)
  WorkedOut(state: c)

# How a stored run ended: the program's value with the state that reached
# it; or waiting on a handed request, with the state saved; or the bound ran
# out first. A refused request aborts the transaction instead.
enum Ran[c, a]:
  RanTo(state: c, value: a)
  RanWaiting(state: c)
  RanOut(state: c)

# Runs `steps` from `start` in this worker: `perform` performs each request
# here and the state stays in memory, one request per item of `bound` at
# most.
def run_in_worker[c, r, p, a, e, x](
  steps: Steps[c, r, p, a], perform: r -> IO[Performed[p, e]], bound: List[x], start: c
) -> IO[Worked[c, a, e]]:
  Steps(next, heard) = steps
  def step(state: c, _: x) -> IO[IterState[c, Worked[c, a, e]]]:
    match next(state):
      case Reached(value): pure(Done(WorkedTo(state, value)))
      case Asks(request):
        performed <- flat_map(perform(request))
        match performed:
          case Replied(reply): pure(Continue(heard(state, request, reply)))
          case Failed(reason): pure(Done(WorkedStopped(reason)))
  worked <- flat_map(fold_until(bound, start, step))
  match worked:
    case Done(result): pure(result)
    case Continue(last):
      match next(last):
        case Reached(value): pure(WorkedTo(last, value))
        case Asks(_): pure(WorkedOut(last))

# Runs `steps` stored, inside one transaction: from `start` (read in that
# transaction), with `answer` answering each request from the store or
# handing it on, and `save` writing each reply before the next request, one
# request per item of `bound` at most. `save` is given the state the run
# carried on from beside the next one, so a store can refuse a write over
# a state another worker moved on. A refused request aborts the
# transaction, so nothing the run saved is kept; a request the store cannot
# answer is handed on and the run waits with what it saved.
def tx_run_stored[s, c, r, p, a, e, x](
  steps: Steps[c, r, p, a], answer: r -> Txn[s, e, Answer[p, e]], save: (c, c) -> Txn[s, e, c],
  bound: List[x], start: c
) -> Txn[s, e, Ran[c, a]]:
  Steps(next, heard) = steps
  def step(state: c, _: x) -> Txn[s, e, IterState[c, Ran[c, a]]]:
    match next(state):
      case Reached(value): tx_pure(Done(RanTo(state, value)))
      case Asks(request):
        answered <- tx_bind(answer(request))
        match answered:
          case Recalled(reply):
            kept <- tx_bind(save(state, heard(state, request, reply)))
            tx_pure(Continue(kept))
          case Handed: tx_pure(Done(RanWaiting(state)))
          case Declined(reason): tx_abort(reason)
  ran <- tx_bind(tx_fold_until(bound, start, step))
  match ran:
    case Done(result): tx_pure(result)
    case Continue(last):
      match next(last):
        case Reached(value): tx_pure(RanTo(last, value))
        case Asks(_): tx_pure(RanOut(last))