silk.machine.actor.
Actors: a machine that performs the effects its transitions queue.
A transition never does work. It queues effects as values, and an actor hands each one to a
performer, in the order they were queued. The performer is an effect function of the program,
so its requirement row names every service the machine's effects use. It can send events back
with Reply.send, for example the result of a request.
Actors keeps the snapshot in memory. Durable has the same functions and saves the
snapshot after every change.
Import as Actors with import silk.machine.actor { Actors }.
Public declarations: 4.
Reply#
pub struct Reply<E>Events a performer sends back to its own actor.
Implementation Reply<E>#
impl<E> Reply<E>Associated function make#
pub fn make() -> Reply<E>Returns a reply without events.
Method take#
pub fn take(self: Self) -> List<E>Returns the events sent so far and consumes the reply.
Method send#
pub effect fn send(self: &mut Self, event: E) -> ()
! OutOfMemoryError
? &mut AllocatorPuts event at the end of the actor's mailbox.
Signal#
pub union Signal<E>What a running actor receives on its channel.
Event#
EventAn event for the machine.
Field event#
pub event: ETick#
TickA timer may be due. The actor sends this to itself.
Stop#
StopStops the actor. Its snapshot keeps the state it had.
Actors#
pub struct ActorsImplementation Actors#
impl ActorsAssociated function settle#
pub effect fn settle<'env, S: Machine<E, C, X>, E, C, X, F, ? R>(
snapshot: &mut Snapshot<S, E, C, X>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
) -> ()
! F | OutOfMemoryError | TransitionLoopError
? R | &mut AllocatorPerforms every queued effect and processes every event in the mailbox, until both are empty.
Details#
Effects run one at a time, in the order they were queued, and before the next event of the mailbox is processed. An effect leaves the snapshot before it is performed, so a failure of the performer does not perform it a second time.
Associated function send#
pub effect fn send<'env, S: Machine<E, C, X>, E, C, X, F, ? R>(
snapshot: &mut Snapshot<S, E, C, X>,
event: E,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
) -> ()
! F | OutOfMemoryError | TransitionLoopError
? R | &mut AllocatorProcesses event, then settles the actor with settle.
Associated function advance#
pub effect fn advance<'env, S: Machine<E, C, X>, E, C, X, F, ? R>(
snapshot: &mut Snapshot<S, E, C, X>,
now: u64,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
) -> ()
! F | OutOfMemoryError | TransitionLoopError
? R | &mut AllocatorMoves the actor's clock to now, in nanoseconds of wall clock time, takes the delayed
transitions that are due, then settles the actor with settle.
Associated function serve#
pub effect fn serve<'env, S: Machine<E, C, X>, E, C, X, F, ? R>(
snapshot: &mut Snapshot<S, E, C, X>,
inbox: &Receiver<E>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
) -> ()
! F | OutOfMemoryError | TransitionLoopError
? R | &mut AllocatorRuns the actor on events from inbox until the machine finishes or the channel closes.
Details#
The actor settles first, so effects left in a restored snapshot are performed before the first event. Fork this effect as a fiber to run the actor beside other work.
Gotchas#
It does not take delayed transitions. Use drive for a machine that has them.
Associated function drive#
pub effect fn drive<'env, S: Machine<E, C, X>, E: 'static, C, X, F, ? R>(
snapshot: &mut Snapshot<S, E, C, X>,
sender: &Sender<Signal<E>>,
inbox: &Receiver<Signal<E>>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
) -> ()
! F | OutOfMemoryError | TransitionLoopError | TaskIdExhaustedError
? R | &mut Allocator | &mut Scheduler | &mut SystemClockRuns the actor with its timers until the machine finishes, a Signal.Stop arrives, or the
channel closes.
Details#
The actor reads the wall clock from SystemClock before each signal and takes the delayed
transitions that are due. While it waits, a child fiber sleeps until the next deadline and
then sends Signal.Tick through sender, so a delayed transition is taken on time without
another event. sender must send to the channel of inbox.
Gotchas#
The actor holds a Sender, so its channel does not close when the other senders are
dropped. Send Signal.Stop to end an actor whose machine has no final state.
Durable#
pub struct DurableActors that save their snapshot after every change, so a program that stops can start again from the last save.
When to use#
Use Durable in place of Actors for a machine that must survive a restart: a workflow, an
order, a session. Each function takes one more argument, save, an effect function that
stores the snapshot, for example as JSON in a file or a database row. To start again, decode
the stored snapshot and pass it to Durable.drive or Durable.serve, which first perform
the effects that were still queued.
Gotchas#
An effect is performed at least one time, not exactly one time: when the program stops while the performer runs, the effect is performed again after the restart. Make effects safe to repeat. An event that was received and not yet saved is lost with the program.
Implementation Durable#
impl DurableAssociated function settle#
pub effect fn settle<'env, S: Machine<E, C, X>, E, C, X, F, G, ? R, ? Q>(
snapshot: &mut Snapshot<S, E, C, X>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
save: effect fn<'env>(&Snapshot<S, E, C, X>) -> () ! G ? Q,
) -> ()
! F | G | OutOfMemoryError | TransitionLoopError
? R | Q | &mut AllocatorPerforms every queued effect and processes every event in the mailbox, until both are empty, and saves the snapshot after each of them.
Details#
save gets the snapshot after each event is processed, with the effects that step queued,
and again after each effect is performed, with the events the performer sent back. A
program that stops between two saves starts again from the last one: an effect that was
being performed is still queued there and is performed again.
Associated function send#
pub effect fn send<'env, S: Machine<E, C, X>, E, C, X, F, G, ? R, ? Q>(
snapshot: &mut Snapshot<S, E, C, X>,
event: E,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
save: effect fn<'env>(&Snapshot<S, E, C, X>) -> () ! G ? Q,
) -> ()
! F | G | OutOfMemoryError | TransitionLoopError
? R | Q | &mut AllocatorProcesses event, then settles the actor with Durable.settle.
Associated function advance#
pub effect fn advance<'env, S: Machine<E, C, X>, E, C, X, F, G, ? R, ? Q>(
snapshot: &mut Snapshot<S, E, C, X>,
now: u64,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
save: effect fn<'env>(&Snapshot<S, E, C, X>) -> () ! G ? Q,
) -> ()
! F | G | OutOfMemoryError | TransitionLoopError
? R | Q | &mut AllocatorMoves the actor's clock to now, in nanoseconds of wall clock time, takes the delayed
transitions that are due, saves the snapshot when one was taken, then settles the actor
with Durable.settle.
Associated function serve#
pub effect fn serve<'env, S: Machine<E, C, X>, E, C, X, F, G, ? R, ? Q>(
snapshot: &mut Snapshot<S, E, C, X>,
inbox: &Receiver<E>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
save: effect fn<'env>(&Snapshot<S, E, C, X>) -> () ! G ? Q,
) -> ()
! F | G | OutOfMemoryError | TransitionLoopError
? R | Q | &mut AllocatorRuns the actor on events from inbox until the machine finishes or the channel closes.
Details#
The actor settles first, so effects left in a restored snapshot are performed before the first event. Fork this effect as a fiber to run the actor beside other work.
Gotchas#
It does not take delayed transitions. Use Durable.drive for a machine that has them.
Associated function drive#
pub effect fn drive<'env, S: Machine<E, C, X>, E: 'static, C, X, F, G, ? R, ? Q>(
snapshot: &mut Snapshot<S, E, C, X>,
sender: &Sender<Signal<E>>,
inbox: &Receiver<Signal<E>>,
perform: effect fn<'env>(X, &mut Reply<E>) -> () ! F ? R,
save: effect fn<'env>(&Snapshot<S, E, C, X>) -> () ! G ? Q,
) -> ()
! F | G | OutOfMemoryError | TransitionLoopError | TaskIdExhaustedError
? R | Q | &mut Allocator | &mut Scheduler | &mut SystemClockRuns the actor with its timers until the machine finishes, a Signal.Stop arrives, or the
channel closes, saving the snapshot after each change.
Details#
The actor reads the wall clock from SystemClock before each signal and takes the delayed
transitions that are due. While it waits, a child fiber sleeps until the next deadline and
then sends Signal.Tick through sender, so a delayed transition is taken on time without
another event. sender must send to the channel of inbox.
Gotchas#
The actor holds a Sender, so its channel does not close when the other senders are
dropped. Send Signal.Stop to end an actor whose machine has no final state.
Category: State machines.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.