Tracing

See the section on capturing and rendering interaction traces in the reference manual.

Interaction traces are recorded as a sequence of TraceEntry records, each carrying a timestamp, an actor identifier, and a trace item. Each TraceEntry describes a single "activation" of an actor: an opportunity for it to run in response to some external event.

TraceEntry = <trace
              @timestamp @"seconds since Unix epoch" double
              @actor ActorId
              @item ActorActivation> .
ActorId = any .

Activations and Turns

Activations come in three kinds: when the actor is started (and given its actorName); when it takes a turn in response to some incoming event; and when it stops (with an exit status).

ActorActivation =
/ <start @actorName Name>
/ @turn TurnDescription
/ <stop @status ExitStatus>
.

Name = <anonymous> / <named @name any> .
ExitStatus = =ok / protocol.Error .

A TurnDescription carries an identifier, a cause, and a series of actions taken by the active actor (that named by the actor field in the containing TraceEntry).

TurnDescription = <turn @id TurnId @cause TurnCause @actions [ActionDescription ...]> .
TurnId = any .

Turn causes

A turn can be triggered for a number of reasons:

  • By some previous turn (TurnCause.turn); this may be because some actor sent the active party an event (a new assertion, a retraction, or a message), in which case the causing turn ID is the turn where the event originated, or because the active party has just been spawned by its parent, in which case the causing turn ID is the turn that performed the spawn action.

  • By the implicit cleanup process at the end of an actor's lifetime (TurnCause.cleanup). The actions in such turns are not under direct programmer control: instead, they embody the automatic retraction of assertions the actor has made that are still outstanding.

  • By termination of a linked task (TurnCause.linkedTaskRelease).

  • By periodic activation (TurnCause.periodicActivation).

  • After a requested delay has expired (TurnCause.delay).

  • By some externally-arriving event outside the Syndicate model (TurnCause.external), such as an event from the operating system, available I/O, the "first cause" of a given program, and so on. Such causes have a free-form human readable description associated with them.

TurnCause =
/ @turn <caused-by @id TurnId>
/ <cleanup>
/ @linkedTaskRelease <linked-task-release @id TaskId @reason LinkedTaskReleaseReason>
/ @periodicActivation <periodic-activation @"`period` is in seconds" @period double>
/ <delay @causingTurn TurnId @"`amount` is in seconds" @amount double>
/ <external @description any>
.

LinkedTaskReleaseReason = =cancelled / =normal .

Turn action descriptions

Turns include a sequence of ActionDescriptions, each describing something that happened at the active party during the turn:

  • dequeue: processing of a received event.
  • enqueue: enqueueing of a new event for delivery if and when the turn completes successfully.
  • dequeueInternal: processing an internally-queued event for one of the actor's own entities.
  • enqueueInternal: scheduling of an internal event for one of the actor's own entities.
  • spawn: creation of a new actor, identified by id and optionally scheduling creation of a link to its spawning actor.
  • link: a record of the actual creation of a link between a spawning and a spawned actor.
  • facetStart and facetStop: startup and shutdown of a facet within the actor, identified by its path.
  • linkedTaskStart: creation of a linked task.
ActionDescription =
/ <dequeue @event TargetedTurnEvent>
/ <enqueue @event TargetedTurnEvent>
/ @dequeueInternal <dequeue-internal @event TargetedTurnEvent>
/ @enqueueInternal <enqueue-internal @event TargetedTurnEvent>
/ <spawn @link bool @id ActorId>
/ <link @parentActor ActorId
        @childToParent protocol.Handle
        @childActor ActorId
        @parentToChild protocol.Handle>
/ @facetStart <facet-start @path [FacetId ...]>
/ @facetStop <facet-stop @path [FacetId ...] @reason FacetStopReason>
/ @linkedTaskStart <linked-task-start @taskName Name @id TaskId>
.

FacetId = any .
TaskId = any .

FacetStopReason =
/ @explicitAction =explicit-action
/ =inert
/ @parentStopping =parent-stopping
/ @actorStopping =actor-stopping
.

Event descriptions

Events sent, received, or processed by an actor are described with TurnEvent structures describing each event. These are carried within TargetedTurnEvent structures, which add information on the target of the event, and which are in turn contained in ActionDescriptions. Event Targets are triples of actor ID, facet ID, and entity oid.

TargetedTurnEvent = <event @target Target @detail TurnEvent> .
Target = <entity @actor ActorId @facet FacetId @oid Oid> .
Oid = any .

A TurnEvent is one of the core types of event in the Syndicated Actor Model:

  • assert: a new assertion, to be referred to later by its handle;
  • retract: a retraction of a previously-established assertion;
  • message: a simple message;
  • sync: a synchronization event; or
  • breakLink: a special kind of retraction notification that results from a broken link to another actor.
TurnEvent =
/ <assert @assertion AssertionDescription @handle protocol.Handle>
/ <retract @handle protocol.Handle>
/ <message @body AssertionDescription>
/ <sync @peer Target>
/ @breakLink <break-link @source ActorId @handle protocol.Handle>
.

Assertion and message bodies can be simple Preserves values, or can be some opaque, system-internal value, represented according to the system concerned.

AssertionDescription = <value @value any> / <opaque @description any> .