334 lines
11 KiB
Racket
334 lines
11 KiB
Racket
#lang scribble/manual
|
|
@require[racket/include]
|
|
@include{prelude.inc}
|
|
|
|
@title[#:tag "low-level-interface"]{Low-level interface}
|
|
|
|
@defmodule[marketplace]
|
|
|
|
At its heart, the interface between each @tech{process} and its
|
|
containing @tech{VM} is based on @tech{handler functions} exchanging
|
|
@tech{event} and @tech{action} structures with the VM. Both events and
|
|
actions are simple Racket structures.
|
|
|
|
This low-level interface between a VM and a process is analogous to
|
|
the @emph{system call interface} of a Unix-like operating system. The
|
|
@secref{high-level-interface} corresponds to the @emph{C library
|
|
interface} of a Unix-like operating system.
|
|
|
|
@section[#:tag "handler-functions"]{Handler Functions}
|
|
|
|
Each @deftech{handler function} is always associated with a particular
|
|
@tech{endpoint}, registered with the VM via
|
|
@racket[endpoint]/@racket[endpoint:]/@racket[add-endpoint]. A handler
|
|
function for a given process with state type @racket[State] has type:
|
|
|
|
@racketblock[(EndpointEvent -> State -> (Transition State))]
|
|
|
|
That is, given an @racket[EndpointEvent] followed by the process's
|
|
current state, the handler should reply with a @racket[Transition]
|
|
containing a new process state and a collection of @racket[Action]s.
|
|
|
|
@deftogether[(
|
|
@deftype[(Handler State) (TrapK State)]
|
|
@deftype[(TrapK State) (EndpointEvent -> (InterruptK State))]
|
|
@deftype[(InterruptK State) (State -> (Transition State))]
|
|
)]{
|
|
|
|
Typed Racket types capturing various notions of handler function.
|
|
|
|
}
|
|
|
|
@section{Messages, Topics and Roles}
|
|
|
|
@declare-exporting[marketplace marketplace/sugar-untyped marketplace/sugar-typed
|
|
#:use-sources (marketplace marketplace/sugar-untyped marketplace/sugar-typed)]
|
|
|
|
@deftogether[(
|
|
@deftype[Message Any]
|
|
@deftype[Topic Any]
|
|
)]{
|
|
|
|
As previously mentioned, @tech{messages} are ordinary Racket values,
|
|
and @tech{topics} are ordinary Racket values which may have embedded
|
|
wildcards.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defproc[(wild) Topic]
|
|
@defthing[#:kind "syntax" ? Topic]
|
|
)]{
|
|
|
|
Each time @racket[?] (or @racket[(wild)]) is used in an expression
|
|
context, it produces a fresh topic wildcard, suitable for use in a
|
|
topic pattern.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[role ([orientation Orientation] [topic Topic] [interest-type InterestType]) #:prefab]
|
|
@deftype[Role role]
|
|
)]{
|
|
|
|
Roles are almost always constructed by the
|
|
@racket[endpoint]/@racket[endpoint:] macros or by the VM
|
|
implementations themselves. User programs generally only need to
|
|
destructure @racket[role] instances.
|
|
|
|
A @racket[role] describes the conversational role of a peer as seen by
|
|
some process. For example, a subscriber to topic @racket['foo] with
|
|
interest-type @racket['participant] might receive a presence
|
|
notification carrying the role
|
|
|
|
@racketblock[(role 'publisher 'foo 'participant)]
|
|
|
|
Notice that the orientation of the role is the opposite of the
|
|
orientation of the endpoint.
|
|
|
|
}
|
|
|
|
@deftype[Orientation (U 'publisher 'subscriber)]{
|
|
|
|
Describes an endpoint's orientation: will it be acting as a publisher
|
|
of messages, or as a subscriber to messages? Publishers (orientation
|
|
@racket['publisher]) tend to use @racket[send-message] and tend to
|
|
respond to feedback from subscribers; subscribers
|
|
(@racket['subscriber]) tend to use @racket[send-feedback] and respond
|
|
to messages from publishers.
|
|
|
|
}
|
|
|
|
@deftype[InterestType (U 'participant 'observer 'everything)]{
|
|
|
|
Using interest-type @racket['participant] in an endpoint's role
|
|
indicates that the endpoint is intending to act as a genuine
|
|
participant in whatever protocol is associated with the endpoint and
|
|
its topic.
|
|
|
|
Using @racket['observer] indicates that the endpoint is intended to
|
|
@emph{monitor} other ongoing (participant) conversations instead.
|
|
Observer endpoints receive presence and absence notifications about
|
|
participant endpoints, but participant endpoints only receive
|
|
notifications about other participant endpoints, and not about
|
|
observer endpoints.
|
|
|
|
The @racket['observer] interest-type is intended to make it easier to
|
|
monitor resource demand and supply. The monitoring endpoints/processes
|
|
can react to changing demand by creating or destroying resources to
|
|
match.
|
|
|
|
Finally, the @racket['everything] interest-type receives notifications
|
|
about presence and absence of @emph{all} the types of endpoint,
|
|
@racket['participant], @racket['observer], and @racket['everything].
|
|
Endpoints with interest-type @racket['everything] are rare: they are
|
|
relevant for managing demand for @emph{observers}, as well as in some
|
|
cases of cross-layer presence/absence propagation. Most programs (and
|
|
even most drivers) will not need to use the @racket['everything]
|
|
interest-type.
|
|
|
|
}
|
|
|
|
@section[#:tag "endpoint-events"]{Endpoint Events}
|
|
|
|
@deftogether[(
|
|
@deftype[EndpointEvent (U PresenceEvent AbsenceEvent MessageEvent)]
|
|
@deftype[PresenceEvent presence-event]
|
|
@deftype[AbsenceEvent absence-event]
|
|
@deftype[MessageEvent message-event]
|
|
)]{
|
|
|
|
Endpoint events are passed to handler functions by VMs, conveying some
|
|
change in the world the process lives in. An endpoint event can signal
|
|
the arrival or departure of a conversational peer, or can deliver a
|
|
message that has been sent on a VM's IPC facility.
|
|
|
|
}
|
|
|
|
@defstruct*[presence-event ([role Role]) #:prefab]{
|
|
|
|
Indicates the arrival of a new conversational partner: an endpoint
|
|
with a topic that intersects our own, with @racket[Orientation]
|
|
opposite to our own.
|
|
|
|
The @racket[presence-event-role] describes the arriving peer, or more
|
|
precisely, describes the shared interest between ourselves and the new
|
|
peer. In particular, the @racket[role-orientation] of the
|
|
@racket[presence-event-role] is the orientation that the @emph{peer}
|
|
supplied in its @racket[add-endpoint] structure.
|
|
|
|
}
|
|
|
|
@defstruct*[absence-event ([role Role] [reason Any]) #:prefab]{
|
|
|
|
Indicates the departure of an existing conversational partner, through
|
|
either an explicit @racket[delete-endpoint] action or the implicit
|
|
deleting of all of a process's endpoints when a process exits.
|
|
|
|
The @racket[absence-event-role] describes the departing peer,
|
|
analogously to @racket[presence-event-role].
|
|
|
|
}
|
|
|
|
@defstruct*[message-event ([role Role] [message Message]) #:prefab]{
|
|
|
|
Indicates the arrival of a message matching the topic pattern in the
|
|
handler's @tech{endpoint}.
|
|
|
|
}
|
|
|
|
@section{Actions}
|
|
|
|
@declare-exporting[marketplace]
|
|
|
|
@deftogether[(
|
|
@deftype[(Action State) (U (PreAction State)
|
|
(yield State)
|
|
(at-meta-level State))]
|
|
@deftype[(PreAction State) (U (add-endpoint State)
|
|
delete-endpoint
|
|
send-message
|
|
(spawn State)
|
|
quit)]
|
|
)]{
|
|
|
|
Actions are requests from a process to its containing VM. If wrapped
|
|
in an @racket[at-meta-level] structure, the action is to apply to
|
|
@emph{the VM's own containing VM}; otherwise, the action applies to
|
|
the process's containing VM.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[at-meta-level ([preaction (PreAction State)]) #:prefab]
|
|
@deftype[(AtMetaLevel State) (at-meta-level State)]
|
|
)]{
|
|
|
|
An @racket[at-meta-level] structure wraps a plain action, and makes it
|
|
apply to the outer VM instead of the inner VM (the default).
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[yield ([k (InterruptK State)]) #:prefab]
|
|
@deftype[(Yield State) (yield State)]
|
|
)]{
|
|
|
|
Because current VM implementations are cooperatively scheduled, it can
|
|
sometimes be necessary to explicitly yield the CPU to other processes
|
|
using a @racket[yield] action. When control returns to the yielding
|
|
process, the @racket[yield-k] is invoked.
|
|
|
|
}
|
|
|
|
@subsection[#:tag "endpoints-and-messages"]{Endpoints and Messages}
|
|
|
|
@deftogether[(
|
|
@defstruct*[add-endpoint ([pre-eid Any] [role Role] [handler (Handler State)]) #:prefab]
|
|
@deftype[(AddEndpoint State) (add-endpoint State)]
|
|
)]{
|
|
|
|
Creates a new endpoint subscribing to the given @racket[Role]. When
|
|
events pertaining to the given role occur, the @racket[Handler] is
|
|
invoked.@note{If invoked @racket[at-meta-level], subscribes to events
|
|
in the containing VM's container.}
|
|
|
|
The name of the new endpoint will be the @racket[pre-eid]; it must be
|
|
unique within the current process, but otherwise can be any value at
|
|
all. If the endpoint's name matches an existing endpoint, and the new
|
|
role is the same as the existing endpoint's role, the handler function
|
|
is @emph{replaced} in the existing endpoint.
|
|
|
|
To delete an endpoint, perform a @racket[delete-endpoint] action built
|
|
with the name of the endpoint to delete.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[delete-endpoint ([pre-eid Any] [reason Any]) #:prefab]
|
|
@deftype[DeleteEndpoint delete-endpoint]
|
|
)]{
|
|
|
|
Deletes an existing endpoint named @racket[pre-eid]. The given
|
|
@racket[reason] is passed along to peer endpoints as part of an
|
|
@racket[absence-event].
|
|
|
|
If no specific reason is needed, it is conventional to supply
|
|
@racket[#f] as the @racket[delete-endpoint-reason]. See also the
|
|
convenience @from[marketplace/sugar-values]{@racket[delete-endpoint]}
|
|
function from @racket[marketplace/sugar-values].
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[send-message ([body Message] [orientation Orientation]) #:prefab]
|
|
@deftype[SendMessage send-message]
|
|
)]{
|
|
|
|
Sends a message to peers.@note{Or, if @racket[at-meta-level], peers of
|
|
the containing VM.} The given @racket[Orientation] should describe the
|
|
role the sender is playing when sending this message: usually, it will
|
|
be @racket['publisher], but when the message is @emph{feedback} for
|
|
some publisher, it will be @racket['subscriber].
|
|
@from[marketplace/sugar-values]{See also the @racket[send-message] and
|
|
@racket[send-feedback] convenience functions from
|
|
@racket[marketplace/sugar-values].}
|
|
|
|
}
|
|
|
|
@subsection{Process Management}
|
|
|
|
@deftogether[(
|
|
@defstruct*[spawn ([spec process-spec] [k (Option (PID -> (InterruptK State)))] [debug-name Any])
|
|
#:prefab]
|
|
@defstruct*[process-spec ([boot (PID -> CoTransition)]) #:prefab]
|
|
@deftype[CoTransition
|
|
(All (Result)
|
|
(All (State) (Transition State) -> Result)
|
|
-> Result)]
|
|
@deftype[(Spawn State) (spawn State)]
|
|
@deftype[ProcessSpec process-spec]
|
|
)]{
|
|
|
|
A @racket[spawn] requests the creation of a sibling process@note{If
|
|
wrapped in an @racket[at-meta-level], the new process will instead be
|
|
a sibling of the creating process's VM.}. The @racket[spawn-k] runs in
|
|
the context of the @emph{creating} process, communicating to it the
|
|
PID of the new process.
|
|
|
|
The @racket[spawn-spec] describes the new process to be created. Its
|
|
@racket[process-spec-boot] field is a function taking the PID of the
|
|
new process and returning a "cotransition". Cotransitions use a
|
|
second-order encoding of existential types to guarantee that the VM
|
|
remains oblivious to the specific process state type of the new
|
|
process. The downside of this approach is its syntactic and type
|
|
complexity: see @racket[spawn:] for an easier-to-use, higher-level
|
|
approach.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defstruct*[quit ([pid (Option PID)] [reason Any]) #:prefab]
|
|
@deftype[Quit quit]
|
|
)]{
|
|
|
|
Kills a sibling process.@note{Or, if @racket[at-meta-level], a sibling
|
|
process of the containing VM.} If @racket[quit-pid] is @racket[#f],
|
|
kills the current process; otherwise, kills the process with the given
|
|
PID. The @racket[quit-reason] is passed on to peers of
|
|
currently-active endpoints in the process to be killed, as part of a
|
|
@racket[absence-event], just as if each active endpoint were deleted
|
|
manually before the process exited.
|
|
|
|
If no specific reason is needed, it is conventional to supply
|
|
@racket[#f] as the @racket[quit-reason].
|
|
|
|
}
|
|
|
|
@deftype[PID Number]{
|
|
|
|
In the current VM implementations, process IDs are simply numbers.
|
|
PIDs are scoped to and allocated by each individual VM instance.
|
|
|
|
}
|