More documentation.
This commit is contained in:
Tony Garnock-Jones
parent
7d2e832a97
commit
628cf190f6
|
|
@ -31,24 +31,65 @@ systematically going through their inboxes.
|
|||
|
||||
@deftech[#:key "process"]{Processes} are ...
|
||||
|
||||
@deftech{Process State} is ...
|
||||
|
||||
@deftech{Events} ...
|
||||
|
||||
@deftech{Actions} ...
|
||||
|
||||
@section{What is a VM?}
|
||||
|
||||
@deftech[#:key "vm"]{Virtual Machines (VMs)} are ...
|
||||
|
||||
@section{Endpoints: Subscription and Advertisement}
|
||||
|
||||
The Marketplace operating system's inter-process communication
|
||||
facility is structured around @deftech[#:key
|
||||
"pub/sub"]{publish/subscribe (pub/sub)} messaging.@note{For a survey
|
||||
of pub/sub messaging, see
|
||||
@hyperlink["http://www.cs.ru.nl/~pieter/oss/manyfaces.pdf"]{"The Many
|
||||
Faces of Publish/Subscribe"}, ACM Computing Surveys, Vol. 35, No. 2,
|
||||
June 2003, pp. 114–131. There's also plenty out there on the Internet;
|
||||
a good starting point is to google for
|
||||
@hyperlink["https://www.google.com/search?q=pub/sub message-oriented middleware"]{pub/sub message-oriented middleware}.}
|
||||
|
||||
@deftech{Endpoints} are ...
|
||||
|
||||
**** orientation
|
||||
**** topics, patterns and messages
|
||||
**** interest-type
|
||||
**** roles
|
||||
|
||||
Always used to describe the role some process is playing in a
|
||||
conversation. Can be used by the currently-running process to describe
|
||||
some role it wishes to play, or can be carried in some
|
||||
A @deftech{role} describes the role some process is playing in a
|
||||
conversation. Concretely, roles are represented by @racket[Role]
|
||||
structures. A role can be used by the currently-running process to
|
||||
describe some role it wishes to play, or can be carried in some
|
||||
@racket[EndpointEvent] to describe the role some @emph{peer} process
|
||||
is playing in a conversation.
|
||||
|
||||
Roles have three parts:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{An @deftech{orientation} (type @racket[Orientation]) describes
|
||||
whether this role is concerned primarily with @emph{producing} or
|
||||
@emph{consuming} messages.}
|
||||
|
||||
@item{A @deftech{topic} is a @deftech{pattern} over messages. Topics
|
||||
perform double duty: they both scope conversations and filter
|
||||
incoming messages. More on topics below.}
|
||||
|
||||
@item{An @deftech{interest-type} (type @racket[InterestType])
|
||||
determines whether the endpoint playing the given role is genuinely
|
||||
a participant in matching conversations or is simply observing the
|
||||
real participants. More on interest-types below.}
|
||||
|
||||
]
|
||||
|
||||
@deftech{Messages} are ...
|
||||
|
||||
@subsection{Topics}
|
||||
|
||||
As mentioned above, topics ...
|
||||
|
||||
@subsection{Interest Types}
|
||||
|
||||
...
|
||||
|
||||
@section{Presence}
|
||||
@section{Nesting, relaying, and levels of discourse}
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
@title{Examples}
|
||||
|
||||
@section{TCP echo server}
|
||||
@section[#:tag "echo-server-example"]{TCP echo server}
|
||||
|
||||
Here is a complete Marketplace program:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,19 +2,104 @@
|
|||
@require[racket/include]
|
||||
@include{prelude.inc}
|
||||
|
||||
@title{High-level interface}
|
||||
@title[#:tag "high-level-interface"]{High-level interface}
|
||||
|
||||
@defmodulelang*[(marketplace
|
||||
marketplace/flow-control
|
||||
marketplace/typed
|
||||
marketplace/typed/flow-control)]
|
||||
|
||||
Programs written for Marketplace differ from normal Racket modules
|
||||
only in their selection of language. A Racket module written with
|
||||
@tt{#lang marketplace}, such as the echo server in
|
||||
@secref["echo-server-example"], specifies a sequence of definitions
|
||||
and startup @tech{actions} for an application. Typically, initial
|
||||
actions spawn application processes and nested VMs, which in turn
|
||||
subscribe to sources of events from the outside world.
|
||||
|
||||
There are a handful of variant languages to choose from:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{@racket[marketplace] is for @emph{untyped} programs, and uses
|
||||
the @secref{tcp-bare} TCP driver;}
|
||||
|
||||
@item{@racket[marketplace/flow-control] is like
|
||||
@racket[marketplace], but uses the flow-controlled @secref{tcp}
|
||||
driver;}
|
||||
|
||||
@item{@racket[marketplace/typed] is like @racket[marketplace], but
|
||||
for @emph{typed} programs;}
|
||||
|
||||
@item{@racket[marketplace/typed/flow-control] is like
|
||||
@racket[marketplace/flow-control], but for typed programs.}
|
||||
|
||||
]
|
||||
|
||||
This high-level interface between a VM and a process is analogous to
|
||||
the @emph{C library interface} of a Unix-like operating system. The
|
||||
@secref{low-level-interface} corresponds to the @emph{system call
|
||||
interface} of a Unix-like operating system.
|
||||
|
||||
@section{Using Marketplace as a library}
|
||||
|
||||
@defmodule*[(marketplace/sugar-untyped
|
||||
marketplace/sugar-typed)]
|
||||
|
||||
Instead of using Racket's @tt{#lang} feature, ordinary Racket programs
|
||||
can use Marketplace features by requiring Marketplace modules
|
||||
directly.
|
||||
|
||||
Such programs need to use @racket[ground-vm]/@racket[ground-vm:] to
|
||||
start the ground-level VM explicitly. They also need to explicitly
|
||||
start any drivers they need; for example, the file
|
||||
@filepath{examples/echo-plain.rkt} uses @racket[ground-vm] along with
|
||||
@racket[tcp] and an initial @racket[endpoint] action:
|
||||
|
||||
@racketblock[
|
||||
(ground-vm
|
||||
tcp
|
||||
(endpoint #:subscriber (tcp-channel ? (tcp-listener 5999) ?)
|
||||
#:conversation (tcp-channel from to _)
|
||||
#:on-presence (spawn #:child (echoer from to))))
|
||||
]
|
||||
|
||||
@deftogether[(
|
||||
@defform[(ground-vm maybe-boot-pid-binding maybe-initial-state initial-action ...)]
|
||||
@defform[(ground-vm: maybe-boot-pid-binding maybe-typed-initial-state initial-action ...)
|
||||
#:grammar
|
||||
[(maybe-boot-pid-binding (code:line)
|
||||
(code:line #:boot-pid id))
|
||||
(maybe-initial-state (code:line)
|
||||
(code:line #:initial-state expr))
|
||||
(maybe-typed-initial-state (code:line)
|
||||
(code:line #:initial-state expr : type))
|
||||
(initial-action expr)]]
|
||||
)]{
|
||||
|
||||
Starts the ground VM, in untyped and typed programs, respectively. If
|
||||
@racket[#:boot-pid] is specified, the given identifier is bound within
|
||||
the form to the PID of the @emph{primordial process} that performs the
|
||||
initial actions. If @racket[#:initial-state] is specified (with a
|
||||
type, for @racket[ground-vm:]), it is used as the initial state for
|
||||
the primordial process; if it is not supplied, the primordial process
|
||||
is given @racket[(void)] as its initial state (and @racket[Void] as
|
||||
its state type).
|
||||
|
||||
}
|
||||
|
||||
@section{#lang marketplace}
|
||||
**** ground-vm, ground-vm:
|
||||
@section{Constructing topics and roles}
|
||||
|
||||
**** ?
|
||||
**** Role
|
||||
**** Orientation
|
||||
**** InterestType
|
||||
|
||||
@section{Constructing transitions}
|
||||
**** transition, transition:, transition/no-state
|
||||
**** cons-trees of actions; null, false, void; use of (when)
|
||||
**** sequence-actions
|
||||
|
||||
@section{Actions}
|
||||
**** Communication-related
|
||||
***** endpoint, endpoint:
|
||||
|
|
|
|||
|
|
@ -4,18 +4,23 @@
|
|||
|
||||
@require[(for-label "../main.rkt")]
|
||||
|
||||
@title{Low-level interface}
|
||||
@title[#:tag "low-level-interface"]{Low-level interface}
|
||||
|
||||
@defmodule[marketplace]
|
||||
|
||||
@section{Handler Functions}
|
||||
|
||||
At its heart, the interface between each @tech{process} and its
|
||||
containing @tech{VM} is based on @emph{handler functions} exchanging
|
||||
@emph{event} and @emph{action} structures with the VM. Both events and
|
||||
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.
|
||||
|
||||
Each handler function is always associated with a particular
|
||||
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{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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue