From 1c79b1723e550da1e00e2bcf034f3cede2e70f19 Mon Sep 17 00:00:00 2001 From: Tony Garnock-Jones Date: Fri, 10 May 2013 15:32:13 -0400 Subject: [PATCH] More text --- marketplace/scribblings/concepts.scrbl | 46 +++++++++++++++++++++----- marketplace/scribblings/lowlevel.scrbl | 4 +-- 2 files changed, 40 insertions(+), 10 deletions(-) diff --git a/marketplace/scribblings/concepts.scrbl b/marketplace/scribblings/concepts.scrbl index 24bba3d..fc72ca8 100644 --- a/marketplace/scribblings/concepts.scrbl +++ b/marketplace/scribblings/concepts.scrbl @@ -53,8 +53,8 @@ information on using Racket events from Marketplace programs. @section{What is a process, what are event handlers?} -A Marketplace @deftech{process} is a collection of event handlers, -plus a piece of private @deftech{process state}. Every +A Marketplace @deftech{process} is a collection of @deftech{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. @@ -66,13 +66,30 @@ handler, then, has the following approximate type: @centered{@italic{State} × @italic{Event} → @italic{State} × (Listof @italic{Action})} -@deftech{Events} ... +Event handlers are registered with the VM by creating @tech{endpoints} +using the @racket[endpoint] macro (described in @secref{Actions}) or +the low-level @racket[add-endpoint] structure (described in +@secref{endpoints-and-messages}). -@deftech{Actions} ... +@deftech{Events}, passed to event handlers, describe the results of +actions from the outside world, neighbouring processes in the VM, or +the VM itself. They are implemented as @racket[struct]s. See +@secref{endpoint-events} for a description of the available event +structures. + +@deftech{Actions}, passed back to the VM by event handlers, describe +actions the process wishes to perform. See @secref{Actions} for the +possible actions a process can take. @section{What is a VM?} -@deftech[#:key "vm"]{Virtual Machines (VMs)} are ... +@deftech[#:key "vm"]{Virtual Machines (VMs)} are simply a collection +of processes, plus a shared medium of communication that the contained +processes use to communicate with each other. VMs offer access to both +their own @emph{internal} network as well as to the @emph{external} +network owned by the VM's own containing VM.@note{Again, the only +exception here is the Ground VM, which interfaces to the underlying +Racket system and so has no containing VM.} @section{Endpoints: Subscription and Advertisement} @@ -86,7 +103,10 @@ 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 the representation of a process's engagement +in some protocol. They pair a description of the process's @tech{role} +in a conversation with an @tech{event handler} that responds to events +relating to that role. A @deftech{role} describes the role some process is playing in a conversation. Concretely, roles are represented by @racket[Role] @@ -114,11 +134,21 @@ Roles have three parts: ] -@deftech{Messages} are ... +@deftech{Messages} are simply Racket data structures. They can be any +value for which @racket[equal?] is defined, any @racket[#:prefab] +structure or non-object structure for which @racket[prop:struct-map] +can be defined. @subsection{Topics} -As mentioned above, topics ... +As mentioned above, topics are simply patterns over messages. They are +represented as normal data structures @emph{with embedded wildcards}. +Use @racket[?] or @racket[(wild)] to construct a wildcard. For +example, given the following definition, + +@racketblock[(struct chat-message (speaker text) #:prefab)] + +TODO HERE @subsection{Interest Types} diff --git a/marketplace/scribblings/lowlevel.scrbl b/marketplace/scribblings/lowlevel.scrbl index 0339c5e..7e20b0e 100644 --- a/marketplace/scribblings/lowlevel.scrbl +++ b/marketplace/scribblings/lowlevel.scrbl @@ -83,7 +83,7 @@ TODO: InterestType } -@section{Endpoint Events} +@section[#:tag "endpoint-events"]{Endpoint Events} @deftogether[( @deftype[EndpointEvent (U PresenceEvent AbsenceEvent MessageEvent)] @@ -167,7 +167,7 @@ process, the @racket[yield-k] is invoked. } -@subsection{Endpoints and Messages} +@subsection[#:tag "endpoints-and-messages"]{Endpoints and Messages} @deftogether[( @defstruct*[add-endpoint ([pre-eid Any] [role Role] [handler (Handler State)]) #:prefab]