Previous: , Up: Actormaps   [Contents][Index]


5.3.3 Using actormaps

As already shown, before using objects in an actormap, one must first create those objects in the context of that actormap:

Procedure: actormap-spawn actormap actor-constructor args …

Spawn an actor inside actormap, but do not commit the transaction. Return a reference to the spawned object and a transactormap.

  • actor-constructor: Constructor for the actor to be spawned.
  • args: Arguments to actor-constructor.
Procedure: actormap-spawn! actormap actor-constructor args …

Like actormap-spawn, but do commit the transaction.

Once objects have been put into an actormap, they may be invoked to perform some action or other. There are several ways to do this, falling into one of two general categories: turns and churns. A turn can be thought of as the performance of a single action, or the processing of a single message. A churn is best understand in terms of a turn as all turns a given actormap can handle without invoking far objects.

Procedure: actormap-turn* actormap to-refr args

Perform a single turn in actormap by invoking to-refr with the list of arguments args. Return the result of the invoked behavior, a new actormap, and a list of new messages generated by the turn.

Procedure: actormap-turn actormap to-refr args …

Like actormap-turn*, but create a new generation of transaction with actormap as the parent and operate in it instead.

Procedure: actormap-turn-message actormap msg [#:error-handler simple-display-error] [#:reckless? #f] [#:catch-errors? #t]

Return the result of msg in the context of actormap. How to handle errors and transactions is controlled by keyword args:

  • error-handler: Procedure to handle errors. It is passed msg, the error, and the stack at the time of the error.
  • reckless?: If #t, operate within actormap instead of creating a new generation; otherwise, create a new generation.
  • catch-errors?: If #t, capture the stack and abort to a prompt; otherwise, propagate the error.
Procedure: actormap-peek actormap to-refr args …

Perform a turn in actormap only to return the results; do not commit the transaction to the transaction history.

  • to-refr: Object to be invoked.
  • args: Arguments passed to to-refr.
Procedure: actormap-poke! actormap to-refr args …

Perform a turn in actormap and commit the results, but ignore any messages generated by it. Return the results.

  • to-refr: Object to be invoked.
  • args: Arguments passed to to-refr.
Procedure: actormap-reckless-poke! actormap to-refr args …

Like actormap-poke!, but commit the results to the current transaction generation without creating a new one. This voids Goblin’s transactionality guarantees like time travel.

Procedure: actormap-run actormap thunk

Execute thunk in actormap, but do not commit the results. Return the results.

Procedure: actormap-run! actormap thunk [#:reckless? #f]

Like actormap-run, and commit the results. If reckless? is #t, do not create a new generation for the turn.

Procedure: actormap-run* actormap thunk

Like actormap-run, and return a reference to the new actormap as well as any messages generated.

Procedure: actormap-churn am msg [#:catch-errors? #t] [#:make-transactormap? #t]

Perform every turn in am possible without needing to invoke far objects to resolve msg, then dispatch messages to the appropriate far objects.

  • catch-errors?: If #f, do not handle errors.
  • make-transactormap?: If #f, operate and commit in am instead of creating a new generation.
Procedure: actormap-churn-run actormap thunk [#:catch-errors? #t]

Evaluate thunk in the context of actormap, performing all possible local invocations to resolve thunk. If catch-errors? is #f, do not handle errors. Return the results, a reference to the new actormap, and any messages generated.

Procedure: actormap-churn-run! actormap thunk [#:catch-errors? #t]

Like actormap-churn-run, but dispatch messages and only return the results of the churn.

When performing any action in a transactormap, one may wish to (but, as has been shown, does not have to) commit the changes to the generational history of the overarching actormap.

Procedure: transactormap-merge! transactormap

Commit the changes in transactormap to the generational history.

Procedure: transactormap-buffer-merge! transactormap

Commit the changes in transactormap to its parent.


Previous: Actormap objects, Up: Actormaps   [Contents][Index]