Tart-tracing NPM

tart-tracing

Stability: 1 - Experimental

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

Contributors

@dalnefre, @tristanls

Overview

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

Usage

To run the below example run:

npm run readme

"use strict";

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

var tracing = tart.tracing();

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 = tracing.sponsor(oneTimeBeh);
actor('bar');

var effect;

console.log('tracing:');
console.log(util.inspect(tracing, {depth: null}));
while ((effect = tracing.dispatch()) != false) {
    console.log('effect:');
    console.log(util.inspect(effect, {depth: null}));
};
console.log('tracing:');
console.log(util.inspect(tracing, {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, context, and cause. When an event is dispatched, the actor context is bound to this parameter and the behavior is executed given the message. The result of processing the message is an effect.

An event has the following attributes:

cause: Event (Default: undefined) The event that caused this event to happen. Will be undefined if this event was not created in an actor behavior.
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.tracing(options)

options: Object (Default: undefined) Optional overrides. WARNING: Implementation of enqueue and dequeue are tightly coupled and should be overridden together.
- annotate: Function function (actor) {} An optional method to wrap/modify newly-created actors.
- 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 tracing 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.
- history: Array An array of effects that represents the history of execution.
- effect: Object Accumulated effects not yet committed to history.
- sponsor: Function function (behavior) {} A capability to create new actors.

Returns the tracing control object.

tracing.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-tracing');
var tracing = tart.tracing();

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

tracing.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 tracing.eventLoop() with no parameters dispatches all events in the event queue.

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

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

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

tracing.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 (traceable) actor and returns the actor reference in form of a capability to send that actor a message.

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