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#

silk
pub struct Reply<E>

Events a performer sends back to its own actor.

Implementation Reply<E>#

silk
impl<E> Reply<E>

Associated function make#

silk
pub fn make() -> Reply<E>

Returns a reply without events.

Method take#

silk
pub fn take(self: Self) -> List<E>

Returns the events sent so far and consumes the reply.

Method send#

silk
pub effect fn send(self: &mut Self, event: E) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Puts event at the end of the actor's mailbox.

Signal#

silk
pub union Signal<E>

What a running actor receives on its channel.

Event#

silk
Event

An event for the machine.

Field event#

silk
pub event: E

Tick#

silk
Tick

A timer may be due. The actor sends this to itself.

Stop#

silk
Stop

Stops the actor. Its snapshot keeps the state it had.

Actors#

silk
pub struct Actors

Implementation Actors#

silk
impl Actors

Associated function settle#

silk
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 Allocator

Performs 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#

silk
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 Allocator

Processes event, then settles the actor with settle.

Associated function advance#

silk
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 Allocator

Moves 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#

silk
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 Allocator

Runs 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#

silk
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 SystemClock

Runs 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#

silk
pub struct Durable

Actors 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#

silk
impl Durable

Associated function settle#

silk
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 Allocator

Performs 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#

silk
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 Allocator

Processes event, then settles the actor with Durable.settle.

Associated function advance#

silk
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 Allocator

Moves 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#

silk
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 Allocator

Runs 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#

silk
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 SystemClock

Runs 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.

View the source of this page