diff --git a/marketplace/scribblings/concepts.scrbl b/marketplace/scribblings/concepts.scrbl index b9b5c19..4a73f23 100644 --- a/marketplace/scribblings/concepts.scrbl +++ b/marketplace/scribblings/concepts.scrbl @@ -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} diff --git a/marketplace/scribblings/examples.scrbl b/marketplace/scribblings/examples.scrbl index f57133d..a1b7923 100644 --- a/marketplace/scribblings/examples.scrbl +++ b/marketplace/scribblings/examples.scrbl @@ -4,7 +4,7 @@ @title{Examples} -@section{TCP echo server} +@section[#:tag "echo-server-example"]{TCP echo server} Here is a complete Marketplace program: diff --git a/marketplace/scribblings/highlevel.scrbl b/marketplace/scribblings/highlevel.scrbl index ca8e14e..d4dcd61 100644 --- a/marketplace/scribblings/highlevel.scrbl +++ b/marketplace/scribblings/highlevel.scrbl @@ -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: diff --git a/marketplace/scribblings/lowlevel.scrbl b/marketplace/scribblings/lowlevel.scrbl index 3cfc637..3890784 100644 --- a/marketplace/scribblings/lowlevel.scrbl +++ b/marketplace/scribblings/lowlevel.scrbl @@ -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: