From 4a4700e1ad02c022c644e24a2bf3c39da74cd395 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Thu, 13 Oct 2022 11:22:10 +0200 Subject: [PATCH] More protocols --- src/protocols/syndicate/service.md | 22 +++ src/protocols/syndicate/trace.md | 166 ++++++++++++++++++++ src/protocols/syndicate/transportAddress.md | 16 ++ 3 files changed, 204 insertions(+) diff --git a/src/protocols/syndicate/service.md b/src/protocols/syndicate/service.md index 91e4442..b13c32e 100644 --- a/src/protocols/syndicate/service.md +++ b/src/protocols/syndicate/service.md @@ -1 +1,23 @@ # Service dependencies + + - [`[syndicate-protocols]/schemas/service.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/service.prs) + +The Service dependency management protocol allows programs to cooperate in declaring mutual +dependencies and scheduling subsystem startups, restarts, and shutdowns. + +For an overview of service definitions and dependencies and a description of the available +assertions and messages, see [the operations manual](../../operation/service.md). + +``` +RequireService = . +RunService = . +RestartService = . + +ServiceState = . +State = =started / =ready / =failed / =complete / @userDefined any . + +ServiceDependency = . +``` +``` +ServiceObject = . +``` diff --git a/src/protocols/syndicate/trace.md b/src/protocols/syndicate/trace.md index 6c328cf..1c70268 100644 --- a/src/protocols/syndicate/trace.md +++ b/src/protocols/syndicate/trace.md @@ -1 +1,167 @@ # Tracing + + - [`[syndicate-protocols]/schemas/trace.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/trace.prs) + +See [the section on capturing and rendering interaction traces](../../guide/tracing.md) 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 = . +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 = +/ +/ @turn TurnDescription +/ +. + +Name = / . +ExitStatus = =ok / protocol.Error . +``` + +A `TurnDescription` carries an `id`entifier, a `cause`, and a series of `actions` taken by the +active actor (that named by the `actor` field in the containing `TraceEntry`). + +``` +TurnDescription = . +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 + `spawn`ed 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](../../glossary.md#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 +/ +/ @linkedTaskRelease +/ @periodicActivation +/ +/ +. + +LinkedTaskReleaseReason = =cancelled / =normal . +``` + +## Turn action descriptions + +Turns include a sequence of `ActionDescription`s, 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`](../../glossary.md#linked-actor) to its spawning actor. + - `link`: a record of the actual creation of a [link](../../glossary.md#linked-actor) between + a spawning and a spawned actor. + - `facetStart` and `facetStop`: startup and shutdown of a [facet](../../glossary.md#facet) + within the actor, identified by its `path`. + - `linkedTaskStart`: creation of a [linked task](../../glossary.md#linked-task). + +``` +ActionDescription = +/ +/ +/ @dequeueInternal +/ @enqueueInternal +/ +/ +/ @facetStart +/ @facetStop +/ @linkedTaskStart +. + +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 +`ActionDescription`s. Event `Target`s are triples of `actor` ID, `facet` ID, and entity `oid`. + +``` +TargetedTurnEvent = . +Target = . +Oid = any . +``` + +A `TurnEvent` is one of the core [types of event in the Syndicated Actor +Model](../../glossary.md#event): + + - `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](../../glossary.md#synchronization); or + - `breakLink`: a special kind of retraction notification that results from a broken + [link](../../glossary.md#linked-actor) to another actor. + +``` +TurnEvent = +/ +/ +/ +/ +/ @breakLink +. +``` + +Assertion and message bodies can be simple [Preserves](../../guide/preserves.md) values, or can +be some opaque, system-internal value, represented according to the system concerned. + +``` +AssertionDescription = / . +``` diff --git a/src/protocols/syndicate/transportAddress.md b/src/protocols/syndicate/transportAddress.md index 282eced..4c6ca6f 100644 --- a/src/protocols/syndicate/transportAddress.md +++ b/src/protocols/syndicate/transportAddress.md @@ -1 +1,17 @@ # Transport addresses + + - [`[syndicate-protocols]/schemas/transportAddress.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/transportAddress.prs) + +These utility definitions allow other schemas to discuss network transport addresses: + + - A `Tcp` address denotes a listening port on a particular host. + - A `Unix` address denotes a UNIX domain socket by its filesystem path. + - A `WebSocket` address contains a `ws://` or `wss://` URL. + - A `Stdio` address denotes the standard input and output of a program. + +``` +Tcp = . +Unix = . +WebSocket = . +Stdio = . +```