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))