<html><head><metahttp-equiv="content-type"content="text/html; charset=utf-8"/><title>1 Concepts</title><linkrel="stylesheet"type="text/css"href="scribble.css"title="default"/><linkrel="stylesheet"type="text/css"href="footnote.css"title="default"/><linkrel="stylesheet"type="text/css"href="racket.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-style.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-racket.css"title="default"/><scripttype="text/javascript"src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><bodyid="scribble-racket-lang-org"><divclass="tocset"><divclass="tocview"><divclass="tocviewlist tocviewlisttopspace"><divclass="tocviewtitle"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><ahref="index.html"class="tocviewlink"data-pltdoc="x">Marketplace:<spanclass="mywbr"> </span> Network-<wbr></wbr>Aware Programming</a></td></tr></table></div><divclass="tocviewsublisttop"style="display: block;"id="tocview_0"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">1 </td><td><ahref="Concepts.html"class="tocviewselflink"data-pltdoc="x">Concepts</a></td></tr><tr><tdalign="right">2 </td><td><ahref="high-level-interface.html"class="tocviewlink"data-pltdoc="x">High-<wbr></wbr>level interface</a></td></tr><tr><tdalign="right">3 </td><td><ahref="low-level-interface.html"class="tocviewlink"data-pltdoc="x">Low-<wbr></wbr>level interface</a></td></tr><tr><tdalign="right">4 </td><td><ahref="Drivers.html"class="tocviewlink"data-pltdoc="x">Drivers</a></td></tr><tr><tdalign="right">5 </td><td><ahref="Management_and_Monitoring.html"class="tocviewlink"data-pltdoc="x">Management and Monitoring</a></td></tr><tr><tdalign="right">6 </td><td><ahref="Examples.html"class="tocviewlink"data-pltdoc="x">Examples</a></td></tr></table></div></div><divclass="tocviewlist"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>1 </td><td><ahref="Concepts.html"class="tocviewselflink"data-pltdoc="x">Concepts</a></td></tr></table><divclass="tocviewsublistbottom"style="display: none;"id="tocview_1"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">1.1 </td><td><ahref="Concepts.html#%28part._.What_is_a_process__what_are_event_handlers_%29"class="tocviewlink"data-pltdoc="x">What is a process, what are event handlers?</a></td></tr><tr><tdalign="right">1.2 </td><td><ahref="Concepts.html#%28part._.What_is_a_.V.M_%29"class="tocviewlink"data-pltdoc="x">What is a VM?</a></td></tr><tr><tdalign="right">1.3 </td><td><ahref="Concepts.html#%28part._.Endpoints__.Subscription_and_.Advertisement%29"class="tocviewlink"data-pltdoc="x">Endpoints:<spanclass="mywbr"> </span> Subscription and Advertisement</a></td></tr><tr><tdalign="right">1.4 </td><td><ahref="Concepts.html#%28part._messages-and-topics%29"class="tocviewlink"data-pltdoc="x">Messages and Topics</a></td></tr><tr><tdalign="right">1.5 </td><td><ahref="Concepts.html#%28part._.Presence%29"class="tocviewlink"data-pltdoc="x">Presence</a></td></tr><tr><tdalign="right">1.6 </td><td><ahref="Concepts.html#%28part._.Nesting__relaying__and_levels_of_discourse%29"class="tocviewlink"data-pltdoc="x">Nesting, relaying, and levels of discourse</a></td></tr></table></div></div></div><divclass="tocsub"><divclass="tocsubtitle">On this page:</div><tableclass="tocsublist"cellspacing="0"><tr><td><spanclass="tocsublinknumber">1.1<tt> </tt></span><ahref="#%28part._.What_is_a_process__what_are_event_handlers_%29"class="tocsubseclink"data-pltdoc="x">What is a process, what are event handlers
virtualized operating system designs to obtain an architecture of
nested <spanstyle="font-style: italic">virtual machines</span> (VMs). Each nested layer is equipped
with its own publish/subscribe network that also propagates
<spanstyle="font-style: italic">presence</span> information about the (dis)appearance of services.</p><p>Throughout this manual, diagrams such as the following will illustrate
various process structures:</p><blockquoteclass="SCentered"><p><imgsrc="pict.png"alt="image"width="389"height="207"/></p></blockquote><p>Rectangular boxes represent VMs. The processes running within each VM
information on using Racket events from Marketplace programs.</p><h4>1.1<tt> </tt><aname="(part._.What_is_a_process__what_are_event_handlers_)"></a>What is a process, what are event handlers?</h4><p>A Marketplace <aname="(tech._proces)"></a><spanstyle="font-style: italic">process</span> is a collection of <aname="(tech._event._handler)"></a><spanstyle="font-style: italic">event
handlers</span>, plus a piece of private <aname="(tech._process._state)"></a><spanstyle="font-style: italic">process state</span>. Every
process<spanclass="NoteBox"><spanclass="NoteContent">The exception to this rule is the Ground VM, which plays
a special role.</span></span> runs within a containing VM.</p><p>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:</p><blockquoteclass="SCentered"><p><spanstyle="font-style: italic">State</span>×<spanstyle="font-style: italic">Event</span>→<spanstyle="font-style: italic">State</span>× (Listof <spanstyle="font-style: italic">Action</span>)</p></blockquote><p>Event handlers are registered with the VM by creating <ahref="Concepts.html#%28tech._endpoint%29"class="techoutside"data-pltdoc="x"><spanclass="techinside">endpoints</span></a>
using the <spanclass="RktSym">endpoint</span> macro (described in <ahref="high-level-interface.html#%28part._endpoint-dsl%29"data-pltdoc="x">Creating endpoints</a>) or
the low-level <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._add-endpoint%29%29"class="RktValLink"data-pltdoc="x">add-endpoint</a></span> structure (described in
<ahref="low-level-interface.html#%28part._endpoints-and-messages%29"data-pltdoc="x">Endpoints and Messages</a>).</p><p><aname="(tech._event)"></a><spanstyle="font-style: italic">Events</span>, 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 <spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29"class="RktStxLink"data-pltdoc="x">struct</a></span>s. See
<ahref="low-level-interface.html#%28part._endpoint-events%29"data-pltdoc="x">Endpoint Events</a> for a description of the available event
structures.</p><p><aname="(tech._action)"></a><spanstyle="font-style: italic">Actions</span>, passed back to the VM by event handlers, describe
actions the process wishes to perform. See <ahref="low-level-interface.html#%28part._.Actions%29"data-pltdoc="x">Actions</a> for the
possible actions a process can take.</p><p>Note that the result of an event handler function is actually a
<spanclass="RktSym"><ahref="high-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Transition%29%29"class="RktValLink"data-pltdoc="x">Transition</a></span> structure; the actual Typed Racket type of event
handlers is <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Trap.K%29%29"class="RktValLink"data-pltdoc="x">TrapK</a></span>, defined in <ahref="low-level-interface.html#%28part._handler-functions%29"data-pltdoc="x">Handler Functions</a>.</p><h4>1.2<tt> </tt><aname="(part._.What_is_a_.V.M_)"></a>What is a VM?</h4><p><aname="(tech._vm)"></a><spanstyle="font-style: italic">Virtual Machines (VMs)</span> 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 <spanstyle="font-style: italic">internal</span> network as well as to the <spanstyle="font-style: italic">external</span>
network owned by the VM’s own containing VM.<spanclass="NoteBox"><spanclass="NoteContent">Again, the only
exception here is the Ground VM, which interfaces to the underlying
Racket system and so has no containing VM.</span></span></p><h4>1.3<tt> </tt><aname="(part._.Endpoints__.Subscription_and_.Advertisement)"></a>Endpoints: Subscription and Advertisement</h4><p>The Marketplace operating system’s inter-process communication
facility is structured around <aname="(tech._pub/sub)"></a><spanstyle="font-style: italic">publish/subscribe (pub/sub)</span> messaging.<spanclass="NoteBox"><spanclass="NoteContent">For a survey
of pub/sub messaging, see
<ahref="http://www.cs.ru.nl/~pieter/oss/manyfaces.pdf">"The Many
Faces of Publish/Subscribe"</a>, 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
<ahref="https://www.google.com/search?q=pub/sub message-oriented middleware">pub/sub message-oriented middleware</a>.</span></span></p><p><aname="(tech._endpoint)"></a><spanstyle="font-style: italic">Endpoints</span> are the representation of a process’s engagement
in some protocol. They pair a description of the process’s <ahref="Concepts.html#%28tech._role%29"class="techoutside"data-pltdoc="x"><spanclass="techinside">role</span></a>
in a conversation with an <ahref="Concepts.html#%28tech._event._handler%29"class="techoutside"data-pltdoc="x"><spanclass="techinside">event handler</span></a> that responds to events
conversation. Concretely, roles are represented by <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Role%29%29"class="RktValLink"data-pltdoc="x">Role</a></span>
<spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Endpoint.Event%29%29"class="RktValLink"data-pltdoc="x">EndpointEvent</a></span> to describe the role some <spanstyle="font-style: italic">peer</span> process
is playing in a conversation.</p><p>Roles have three parts:</p><ul><li><p>An <aname="(tech._orientation)"></a><spanstyle="font-style: italic">orientation</span> (type <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Orientation%29%29"class="RktValLink"data-pltdoc="x">Orientation</a></span>) describes
whether this role is concerned primarily with <spanstyle="font-style: italic">producing</span> or
<spanstyle="font-style: italic">consuming</span> messages.</p></li><li><p>A <aname="(tech._topic)"></a><spanstyle="font-style: italic">topic</span> is a <aname="(tech._pattern)"></a><spanstyle="font-style: italic">pattern</span> over messages. Topics
perform double duty: they both scope conversations and filter
incoming messages. More on topics below.</p></li><li><p>An <aname="(tech._interest._type)"></a><spanstyle="font-style: italic">interest-type</span> (type <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._.Interest.Type%29%29"class="RktValLink"data-pltdoc="x">InterestType</a></span>)
determines whether the endpoint playing the given role is genuinely
a participant in matching conversations or is simply observing the
real participants. See <ahref="high-level-interface.html#%28part._endpoint-dsl%29"data-pltdoc="x">Creating endpoints</a> for more on
interest-types.</p></li></ul><h4>1.4<tt> </tt><aname="(part._messages-and-topics)"></a>Messages and Topics</h4><p><aname="(tech._message)"></a><spanstyle="font-style: italic">Messages</span> are simply Racket data structures. They can be any
value for which <spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/booleans.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29"class="RktValLink"data-pltdoc="x">equal?</a></span> is defined, any <spanclass="RktPn">#:prefab</span>
structure, most <spanclass="RktPn">#:transparent</span> structures, or any non-object
structure for which <spanclass="RktSym">prop:struct-map</span> can be defined.</p><p>As mentioned above, topics are simply patterns over messages. They are
represented as normal data structures <spanstyle="font-style: italic">with embedded wildcards</span>.
Use <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span> or <spanclass="RktPn">(</span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._wild%29%29"class="RktValLink"data-pltdoc="x">wild</a></span><spanclass="RktPn">)</span> to construct a wildcard. For
example, given the following definition,</p><blockquoteclass="SCodeFlow"><p><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29"class="RktStxLink"data-pltdoc="x">struct</a></span><spanclass="hspace"> </span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">speaker</span><spanclass="hspace"> </span><spanclass="RktSym">text</span><spanclass="RktPn">)</span><spanclass="hspace"> </span><spanclass="RktPn">#:transparent</span><spanclass="RktPn">)</span></p></blockquote><p>we can not only create instances that might be used with
<spanclass="RktSym"><ahref="high-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-values..rkt%29._send-message%29%29"class="RktValLink"data-pltdoc="x">send-message</a></span>,</p><blockquoteclass="SCodeFlow"><p><spanclass="RktPn">(</span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktVal">"Tony"</span><spanclass="hspace"> </span><spanclass="RktVal">"Hello World!"</span><spanclass="RktPn">)</span></p></blockquote><p>but also create topic patterns using <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span>. For example, this
pattern matches anything said by <spanclass="RktVal">"Tony"</span>:</p><blockquoteclass="SCodeFlow"><p><spanclass="RktPn">(</span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktVal">"Tony"</span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="RktPn">)</span></p></blockquote><p>This pattern matches chat-messages sent by anyone saying "Hello":</p><blockquoteclass="SCodeFlow"><p><spanclass="RktPn">(</span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="hspace"> </span><spanclass="RktVal">"Hello"</span><spanclass="RktPn">)</span></p></blockquote><p>And finally, this pattern matches any chat-message at all:</p><blockquoteclass="SCodeFlow"><p><spanclass="RktPn">(</span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="RktPn">)</span></p></blockquote><p>Patterns can be nested. For instance, given the above definition of
greeting anybody at all:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29"class="RktStxLink"data-pltdoc="x">struct</a></span><spanclass="hspace"> </span><spanclass="RktSym">greeting</span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">target</span><spanclass="RktPn">)</span><spanclass="hspace"> </span><spanclass="RktPn">#:transparent</span><spanclass="RktPn">)</span></td></tr><tr><td><spanclass="RktPn">(</span><spanclass="RktSym">chat-message</span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="hspace"> </span><spanclass="RktPn">(</span><spanclass="RktSym">greeting</span><spanclass="hspace"> </span><spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-untyped..rkt%29._~3f%29%29"class="RktValLink"data-pltdoc="x">?</a></span><spanclass="RktPn">)</span><spanclass="RktPn">)</span></td></tr></table></blockquote><h4>1.5<tt> </tt><aname="(part._.Presence)"></a>Presence</h4><p><aname="(tech._presence)"></a><spanstyle="font-style: italic">Presence</span> (respectively its opposite, <aname="(tech._absence)"></a><spanstyle="font-style: italic">absence</span>) is
process’s endpoint causes <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._presence-event%29%29"class="RktValLink"data-pltdoc="x">presence-event</a></span>s to be sent to both
crashes, or an endpoint is withdrawn with <spanclass="RktSym"><ahref="high-level-interface.html#%28def._%28%28lib._marketplace%2Fsugar-values..rkt%29._delete-endpoint%29%29"class="RktValLink"data-pltdoc="x">delete-endpoint</a></span>, a
corresponding <spanclass="RktSym"><ahref="low-level-interface.html#%28def._%28%28lib._marketplace%2Fmain..rkt%29._absence-event%29%29"class="RktValLink"data-pltdoc="x">absence-event</a></span> is sent to the remaining
endpoint.</p><h4>1.6<tt> </tt><aname="(part._.Nesting__relaying__and_levels_of_discourse)"></a>Nesting, relaying, and levels of discourse</h4><p>Because VMs can be nested, and each VM has an IPC network of its own
for the use of its processes, information sometimes needs to be
relayed from a VM’s external network to its internal network and vice
versa.</p><p>In general, the protocol messages sent across a VM’s internal network
may be quite different in syntax and meaning from those sent across
the same VM’s external network: consider the case of the
<ahref="Examples.html#%28part._chat-server-example%29"data-pltdoc="x">TCP chat server</a>, which employs a nested VM to separate
out TCP-related messages from higher-level, application-specific chat
messages:</p><blockquoteclass="SCentered"><p><imgsrc="pict_2.png"alt="image"width="355"height="214"/></p></blockquote><p>Each VM’s network corresponds to a distinct <spanstyle="font-style: italic">level of discourse</span>.
TCP-IP/HTTP/Webapp stack could perhaps be represented as</p><blockquoteclass="SCentered"><p><imgsrc="pict_3.png"alt="image"width="241"height="260"/></p></blockquote><divclass="navsetbottom"><spanclass="navleft"> </span><spanclass="navright"> <ahref="index.html"title="backward to "Marketplace: Network-Aware Programming""data-pltdoc="x">← prev</a> <ahref="index.html"title="up to "Marketplace: Network-Aware Programming""data-pltdoc="x">up</a> <ahref="high-level-interface.html"title="forward to "2 High-level interface""data-pltdoc="x">next →</a></span> </div></div></div><divid="contextindicator"> </div></body></html>