More documentation.
This commit is contained in:
parent
7d2e832a97
commit
628cf190f6
|
@ -31,24 +31,65 @@ systematically going through their inboxes.
|
||||||
|
|
||||||
@deftech[#:key "process"]{Processes} are ...
|
@deftech[#:key "process"]{Processes} are ...
|
||||||
|
|
||||||
|
@deftech{Process State} is ...
|
||||||
|
|
||||||
|
@deftech{Events} ...
|
||||||
|
|
||||||
|
@deftech{Actions} ...
|
||||||
|
|
||||||
@section{What is a VM?}
|
@section{What is a VM?}
|
||||||
|
|
||||||
@deftech[#:key "vm"]{Virtual Machines (VMs)} are ...
|
@deftech[#:key "vm"]{Virtual Machines (VMs)} are ...
|
||||||
|
|
||||||
@section{Endpoints: Subscription and Advertisement}
|
@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 ...
|
@deftech{Endpoints} are ...
|
||||||
|
|
||||||
**** orientation
|
A @deftech{role} describes the role some process is playing in a
|
||||||
**** topics, patterns and messages
|
conversation. Concretely, roles are represented by @racket[Role]
|
||||||
**** interest-type
|
structures. A role can be used by the currently-running process to
|
||||||
**** roles
|
describe some role it wishes to play, or can be carried in some
|
||||||
|
|
||||||
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
|
|
||||||
@racket[EndpointEvent] to describe the role some @emph{peer} process
|
@racket[EndpointEvent] to describe the role some @emph{peer} process
|
||||||
is playing in a conversation.
|
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{Presence}
|
||||||
@section{Nesting, relaying, and levels of discourse}
|
@section{Nesting, relaying, and levels of discourse}
|
||||||
|
|
|
@ -4,7 +4,7 @@
|
||||||
|
|
||||||
@title{Examples}
|
@title{Examples}
|
||||||
|
|
||||||
@section{TCP echo server}
|
@section[#:tag "echo-server-example"]{TCP echo server}
|
||||||
|
|
||||||
Here is a complete Marketplace program:
|
Here is a complete Marketplace program:
|
||||||
|
|
||||||
|
|
|
@ -2,19 +2,104 @@
|
||||||
@require[racket/include]
|
@require[racket/include]
|
||||||
@include{prelude.inc}
|
@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}
|
@section{Constructing topics and roles}
|
||||||
|
|
||||||
**** ?
|
**** ?
|
||||||
**** Role
|
**** Role
|
||||||
**** Orientation
|
**** Orientation
|
||||||
**** InterestType
|
**** InterestType
|
||||||
|
|
||||||
@section{Constructing transitions}
|
@section{Constructing transitions}
|
||||||
**** transition, transition:, transition/no-state
|
**** transition, transition:, transition/no-state
|
||||||
**** cons-trees of actions; null, false, void; use of (when)
|
**** cons-trees of actions; null, false, void; use of (when)
|
||||||
**** sequence-actions
|
**** sequence-actions
|
||||||
|
|
||||||
@section{Actions}
|
@section{Actions}
|
||||||
**** Communication-related
|
**** Communication-related
|
||||||
***** endpoint, endpoint:
|
***** endpoint, endpoint:
|
||||||
|
|
|
@ -4,18 +4,23 @@
|
||||||
|
|
||||||
@require[(for-label "../main.rkt")]
|
@require[(for-label "../main.rkt")]
|
||||||
|
|
||||||
@title{Low-level interface}
|
@title[#:tag "low-level-interface"]{Low-level interface}
|
||||||
|
|
||||||
@defmodule[marketplace]
|
@defmodule[marketplace]
|
||||||
|
|
||||||
@section{Handler Functions}
|
|
||||||
|
|
||||||
At its heart, the interface between each @tech{process} and its
|
At its heart, the interface between each @tech{process} and its
|
||||||
containing @tech{VM} is based on @emph{handler functions} exchanging
|
containing @tech{VM} is based on @tech{handler functions} exchanging
|
||||||
@emph{event} and @emph{action} structures with the VM. Both events and
|
@tech{event} and @tech{action} structures with the VM. Both events and
|
||||||
actions are simple Racket structures.
|
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
|
@tech{endpoint}, registered with the VM via
|
||||||
@racket[endpoint]/@racket[endpoint:]/@racket[add-endpoint]. A handler
|
@racket[endpoint]/@racket[endpoint:]/@racket[add-endpoint]. A handler
|
||||||
function for a given process with state type @racket[State] has type:
|
function for a given process with state type @racket[State] has type:
|
||||||
|
|
Loading…
Reference in New Issue