diff --git a/marketplace/scribblings/concepts.scrbl b/marketplace/scribblings/concepts.scrbl index a2e10fb..24bba3d 100644 --- a/marketplace/scribblings/concepts.scrbl +++ b/marketplace/scribblings/concepts.scrbl @@ -6,19 +6,65 @@ Marketplace integrates ideas from both distributed systems and virtualized operating system designs to obtain an architecture of -nested @emph{virtual machines}. Each nested layer is equipped with its -own publish/subscribe network that also propagates @emph{presence} -information about the (dis)appearance of services. +nested @emph{virtual machines} (VMs). Each nested layer is equipped +with its own publish/subscribe network that also propagates +@emph{presence} information about the (dis)appearance of services. -The result suggests a @emph{marketplace} metaphor, where communicating -programs exist in a noisy, crowded, even chaotic context, rather than -in a quiet place systematically going through their inboxes. +Throughout this manual, diagrams such as the following will illustrate +various process structures: + +@vm-figure[(vm (vm-label "Ground Virtual Machine") + (network-label "Ground-level Network Language") + (process "A Process") + (process "Another Process") + (parameterize ((process-height (* 2/3 (process-height))) + (vm-height (* 2 (vm-height)))) + (vm (vc-append (vm-label "Nested VMs are") + (vm-label "processes too")) + (network-label "App-specific language") + (process "Process") + (process "Process") + (process "Process"))) + (parameterize ((process-height (* 5/4 (process-height)))) + (process "Yet another process")) + (parameterize ((process-height (* 2/3 (process-height)))) + (vm (vm-label "Another Nested VM") + (network-label "Another language") + (process "Process") + (process "Process"))))] + +Rectangular boxes represent VMs. The processes running within each VM +are placed atop its box. The narrow rectangular strip at the top of +each VM's box represents the network connecting all the VM's processes +to each other; it will frequently contain a short description of the +protocols used for communication across the represented network. + +A central feature of Marketplace is that VMs are nothing more than +regular processes, making them recursively nestable. Each VM supports +a collection of processes all its own, and its internal IPC medium +carries a VM-specific protocol that is often different from the +protocol spoken by its containing VM. + +The outermost VM is called the @emph{ground VM}. The protocol spoken +by processes running within the ground VM is a simple protocol +relating Racket's @tech{synchronizable events} to Marketplace network +messages. See @secref{writing-new-drivers} and @secref{Drivers} for +information on using Racket events from Marketplace programs. @section{What is a process, what are event handlers?} -@deftech[#:key "process"]{Processes} are ... +A Marketplace @deftech{process} is a collection of event handlers, +plus a piece of private @deftech{process state}. Every +process@note{The exception to this rule is the Ground VM, which plays +a special role.} runs within a containing VM. -@deftech{Process State} is ... +When an event occurs that is relevant to a process, one of its event +handlers is called with the process's current state and a description +of the event. The handler is expected to return an updated state value +and a collection of actions for the containing VM to perform. An event +handler, then, has the following approximate type: + +@centered{@italic{State} × @italic{Event} → @italic{State} × (Listof @italic{Action})} @deftech{Events} ... diff --git a/marketplace/scribblings/marketplace.scrbl b/marketplace/scribblings/marketplace.scrbl index 8171b4f..ba78e7d 100644 --- a/marketplace/scribblings/marketplace.scrbl +++ b/marketplace/scribblings/marketplace.scrbl @@ -66,7 +66,7 @@ communicate with other networks, via yet other networks. @local-table-of-contents[] -@include-section["background.scrbl"] +@;@include-section["background.scrbl"] @include-section["concepts.scrbl"] @include-section["highlevel.scrbl"] @include-section["lowlevel.scrbl"] diff --git a/marketplace/scribblings/writing-drivers.scrbl b/marketplace/scribblings/writing-drivers.scrbl index 46a8418..2aef963 100644 --- a/marketplace/scribblings/writing-drivers.scrbl +++ b/marketplace/scribblings/writing-drivers.scrbl @@ -2,7 +2,7 @@ @require[racket/include] @include{prelude.inc} -@title{Writing New Drivers} +@title[#:tag "writing-new-drivers"]{Writing New Drivers} *** ground-vm's usage of Racket evt?s *** pseudo-substruct