tart-stepping

Stepping configuration implementation for Tiny Actor Run-Time in JavaScript.

Contributors

@dalnefre, @tristanls

Overview

Stepping configuration implementation for Tiny Actor Run-Time in JavaScript.

• Usage
• Tests
• Documentation
• Sources

Usage

To run the below example run:

npm run readme

"use strict";

var tart = require('../index.js');
var util = require('util');

var stepping = tart.stepping();

var createdBeh = function createdBeh(message) {};
var becomeBeh = function becomeBeh(message) {};

var oneTimeBeh = function oneTimeBeh(message) {
    var actor = this.sponsor(createdBeh); // create
    actor('foo'); // send
    this.behavior = becomeBeh; // become
};

var actor = stepping.sponsor(oneTimeBeh);
actor('bar');

var effect;

console.log('stepping:');
console.log(util.inspect(stepping, {depth: null}));
while ((effect = stepping.dispatch()) !== false) {
    console.log('effect:');
    console.log(util.inspect(effect, {depth: null}));
};
console.log('stepping:');
console.log(util.inspect(stepping, {depth: null}));

Tests

npm test

Documentation

Events

An event is an abstraction around the concept of a message being delivered to the actor. It is a tuple of a message and context. When an event is dispatched, the actor context is bound to this
and the context.behavior is executed with the message as a parameter. The result of processing the message is an effect.

An event has the following attributes:

• context: Object Actor context the message was delivered to.
• message: Any Message that was delivered.

Effects

An effect is an Object that is the effect of dispatching an event. It has the following attributes:

• became: Function (Default: undefined) function (message) {} If the actor changed its behavior as a result of processing a message, the new behavior it became is referenced here.
• behavior: Function (Default: undefined) function (message) {} The behavior that executed to cause this effect, if any.
• created: Array An array of created contexts. A context is the execution context of an actor behavior (the value of this when the behavior executes).
• event: Object (Default: undefined) The event that is the cause of this effect, if any.
• exception: Error (Default: undefined) If dispatching the event caused an exception, that exception is stored here.
• sent: Array An array of events that represent messages sent by the actor as a result of processing a message.

Public API

• tart.stepping([options])
• stepping.dispatch()
• stepping.eventLoop([control])
• stepping.sponsor(behavior)

tart.stepping(options)

• options: Object (Default: undefined) Optional overrides.
  WARNING: Implementation of enqueue and dequeue are tightly coupled and should be overridden together.
  • constructConfig: Function (Default: function (options) {}) function (options) {} Configuration creation function that is given options. It should return a capability function (behavior) {} to create new actors.
  • enqueue: Function function (eventQueue, events){} Function that enqueues the new events onto the eventQueue in place, causing side-effects (Example: function (eventQueue, events){ Array.prototype.push.apply(eventQueue, events); }).
  • dequeue: Function function (eventQueue){} Function that returns next event to be dispatched given an eventQueue (Example: function (eventQueue){ return eventQueue.shift(); }).
• Return: Object The stepping control object.
  • dispatch: Function function () {} Function to call in order to dispatch a single event.
  • eventLoop: Function function ([control]) {} Function to call in order to dispatch multiple events.
  • effect: Object Accumulated effects from current step.
  • sponsor: Function function (behavior) {} A capability to create new actors.

Create a stepping control object.

stepping.dispatch()

• Return: Effect or false. Effect of dispatching the next event or false if no events exists for dispatch.

Dispatch the next event.

var tart = require('tart-stepping');
var stepping = tart.stepping();

var effect = stepping.effect;
console.dir(effect);
while ((effect = stepping.dispatch()) !== false) {
    console.dir(effect);
}

stepping.eventLoop([control])

• control: Object (Default: undefined) Optional overrides.
  • count: Number (Default: undefined) Maximum number of events to dispatch, or unlimited if undefined.
  • fail: Function function (exception) {} Function called to report exceptions thrown from an actor behavior. Exceptions are thrown by default. (Example: function (exception) {/*ignore exceptions*/}).
  • log: Function function (effect) {} Function called with every effect resulting from an event dispatch.
• Return: Boolean true if event queue is exhausted, false otherwise.

Dispatch events in a manner provided by control.

By default, calling stepping.eventLoop() with no parameters dispatches all events in the event queue.

var tart = require('tart-stepping');
var stepping = tart.stepping();

var actor = stepping.sponsor(function (message) {
    console.log(message); 
});
actor('foo');
actor('bar');
actor('baz');

stepping.eventLoop();
// foo
// bar
// baz

stepping.sponsor(behavior)

• behavior: Function function (message) {} Actor behavior to invoke every time an actor receives a message.
• Return: Function function (message) {} Actor reference in form of a capability that can be invoked to send the actor a message.

Creates a new actor and returns the actor reference in form of a capability to send that actor a message.

var tart = require('tart-stepping');
var stepping = tart.stepping();
var actor = stepping.sponsor(function (message) {
    console.log('got message', message);
    console.log(this.self);
    console.log(this.behavior);
    console.log(this.sponsor); 
});

Sources

• Tiny Actor Run-Time (JavaScript)