215 lines
106 KiB
HTML
215 lines
106 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>11.5 Places</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="icons.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewlink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewselflink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewlink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</a></td></tr><tr><t
|
||
|
|
take advantage of machines with multiple processors, cores, or
|
||
|
|
hardware threads.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>Currently, parallel support for places is enabled
|
||
|
|
on all platforms that support Racket <a href="implementations.html#%28tech._c%29" class="techoutside" data-pltdoc="x"><span class="techinside">CS</span></a>, the default implementation of Racket.
|
||
|
|
The <a href="implementations.html#%28tech._3m%29" class="techoutside" data-pltdoc="x"><span class="techinside">3m</span></a> implementation also supports parallel execution of places
|
||
|
|
by default on Windows, Linux x86/x86_64, and Mac OS x86/x86_64. To
|
||
|
|
enable support for other platforms with <a href="implementations.html#%28tech._3m%29" class="techoutside" data-pltdoc="x"><span class="techinside">3m</span></a>, use <span class="nobreak"><span class="stt">--enable-places</span></span> with
|
||
|
|
<span class="stt">configure</span> when building Racket. The <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-enabled~3f%29%29" class="RktValLink" data-pltdoc="x">place-enabled?</a></span>
|
||
|
|
function reports whether places run in parallel.</p><p>Implementation and operating-system constraints may limit the
|
||
|
|
scalability of places. For example, although places can perform
|
||
|
|
garbage collections in parallel in the <a href="implementations.html#%28tech._c%29" class="techoutside" data-pltdoc="x"><span class="techinside">CS</span></a> implementation or independently
|
||
|
|
in the <a href="implementations.html#%28tech._3m%29" class="techoutside" data-pltdoc="x"><span class="techinside">3m</span></a> implementation, a garbage collection
|
||
|
|
may need to manipulate a page table that is shared across all
|
||
|
|
places, and that shared page table can be a bottleneck with enough
|
||
|
|
places—<wbr></wbr>perhaps around 8 or 16.</p></blockquote></blockquote></blockquote><p>A <a name="(tech._place)"></a><span style="font-style: italic">place</span> is a parallel task that is effectively a separate
|
||
|
|
instance of the Racket virtual machine, although all places run within
|
||
|
|
a single operating-system process. Places communicate through
|
||
|
|
<a name="(tech._place._channel)"></a><span style="font-style: italic">place channels</span>, which are endpoints for a two-way buffered
|
||
|
|
communication.</p><p>To a first approximation, place channels support only immutable,
|
||
|
|
transparent values as messages. In addition, place
|
||
|
|
channels themselves can be sent across channels to establish new
|
||
|
|
(possibly more direct) lines of communication in addition to any
|
||
|
|
existing lines. Finally, mutable values produced by
|
||
|
|
<span class="RktSym"><a href="flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._shared-flvector%29%29" class="RktValLink" data-pltdoc="x">shared-flvector</a></span>, <span class="RktSym"><a href="flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._make-shared-flvector%29%29" class="RktValLink" data-pltdoc="x">make-shared-flvector</a></span>,
|
||
|
|
<span class="RktSym"><a href="fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._shared-fxvector%29%29" class="RktValLink" data-pltdoc="x">shared-fxvector</a></span>, <span class="RktSym"><a href="fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._make-shared-fxvector%29%29" class="RktValLink" data-pltdoc="x">make-shared-fxvector</a></span>,
|
||
|
|
<span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._shared-bytes%29%29" class="RktValLink" data-pltdoc="x">shared-bytes</a></span>, and <span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._make-shared-bytes%29%29" class="RktValLink" data-pltdoc="x">make-shared-bytes</a></span> can be sent
|
||
|
|
across place channels; mutation of such values is visible to all
|
||
|
|
places that share the value, because they are allowed in a
|
||
|
|
<a name="(tech._shared._memory._space)"></a><span style="font-style: italic">shared memory space</span>. See <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValLink" data-pltdoc="x">place-message-allowed?</a></span>.</p><p>A <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a> can be used as a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a>
|
||
|
|
(see <a href="sync.html" data-pltdoc="x">Events</a>) to receive a value through the channel.
|
||
|
|
A <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a> is <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> when
|
||
|
|
a message is available on the channel, and the <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a>’s
|
||
|
|
<a href="sync.html#%28tech._synchronization._result%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronization result</span></a> is the message (which is removed on
|
||
|
|
synchronization). A place
|
||
|
|
can also receive messages with <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-get%29%29" class="RktValLink" data-pltdoc="x">place-channel-get</a></span>, and
|
||
|
|
messages can be sent with <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29" class="RktValLink" data-pltdoc="x">place-channel-put</a></span>.</p><p>Two <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channels</span></a> are <span class="RktSym"><a href="Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29" class="RktValLink" data-pltdoc="x">equal?</a></span> if they are endpoints
|
||
|
|
for the same underlying channels while both or neither is a
|
||
|
|
<a href="places.html#%28tech._place._descriptor%29" class="techoutside" data-pltdoc="x"><span class="techinside">place descriptor</span></a>. <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">Place channels</span></a> can be <span class="RktSym"><a href="Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29" class="RktValLink" data-pltdoc="x">equal?</a></span>
|
||
|
|
without being <span class="RktSym"><a href="Equality.html#%28def._%28%28quote._~23~25kernel%29._eq~3f%29%29" class="RktValLink" data-pltdoc="x">eq?</a></span> after being sent messages through a
|
||
|
|
<a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a>.</p><p>Constraints on messages across a place channel—<wbr></wbr>and therefore on the
|
||
|
|
kinds of data that places share—<wbr></wbr>enable greater parallelism than
|
||
|
|
<span class="RktSym"><a href="futures.html#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span>, even including separate <a href="eval-model.html#%28tech._garbage._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">garbage collection</span></a> of
|
||
|
|
separate places. At the same time, the setup and communication costs
|
||
|
|
for places can be higher than for <a href="futures.html#%28tech._future%29" class="techoutside" data-pltdoc="x"><span class="techinside">futures</span></a>.</p><p>For example, the following expression launches two places, echoes a
|
||
|
|
message to each, and then waits for the places to terminate:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29" class="RktStxLink" data-pltdoc="x">let</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">pls</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="for.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for%2Flist%29%29" class="RktStxLink" data-pltdoc="x">for/list</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">i</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="sequences.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-range%29%29" class="RktValLink" data-pltdoc="x">in-range</a></span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span><span class="hspace"> </span><span class="RktVal">"place-worker.rkt"</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">place-main</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="for.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for%29%29" class="RktStxLink" data-pltdoc="x">for</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">i</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="sequences.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-range%29%29" class="RktValLink" data-pltdoc="x">in-range</a></span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktPn">)</span><span class="RktPn">]</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">[</span><span class="RktSym">p</span><span class="hspace"> </span><span class="RktSym">pls</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29" class="RktValLink" data-pltdoc="x">place-channel-put</a></span><span class="hspace"> </span><span class="RktSym">p</span><span class="hspace"> </span><span class="RktSym">i</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"~a\n"</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-get%29%29" class="RktValLink" data-pltdoc="x">place-channel-get</a></span><span class="hspace"> </span><span class="RktSym">p</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%
|
||
|
|
is separate from the above code) must export the
|
||
|
|
<span class="RktSym">place-main</span> function that each place executes, where
|
||
|
|
<span class="RktSym">place-main</span> must accept a single <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a>
|
||
|
|
argument:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"place-worker.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._provide%29%29" class="RktStxLink" data-pltdoc="x">provide</a></span><span class="hspace"> </span><span class="RktSym">place-main</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">place-main</span><span class="hspace"> </span><span class="RktSym">pch</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29" class="RktValLink" data-pltdoc="x">place-channel-put</a></span><span class="hspace"> </span><span class="RktSym">pch</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29" class="RktValLink" data-pltdoc="x">format</a></span><span class="hspace"> </span><span class="RktVal">"Hello from place ~a"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-get%29%29" class="RktValLink" data-pltdoc="x">place-channel-get</a></span><span class="hspace"> </span><span class="RktSym">pch</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>Place channels are subject to <a href="eval-model.html#%28tech._garbage._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">garbage collection</span></a>, like other
|
||
|
|
Racket values, and a <a href="eval-model.html#%28tech._thread%29" class="techoutside" data-pltdoc="x"><span class="techinside">thread</span></a> that is blocked reading from a
|
||
|
|
<a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a> can be garbage collected if <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place
|
||
|
|
channel</span></a>’s writing end becomes unreachable. <a name="(elem._(caveat._place-channel-gc))"></a>However, unlike normal <a href="channel.html#%28tech._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">channel</span></a> blocking,
|
||
|
|
if otherwise unreachable threads are mutually blocked on place
|
||
|
|
channels that are reachable only from the same threads, the threads
|
||
|
|
and place channels are all considered reachable, instead of
|
||
|
|
unreachable.</p><p>When a place is created, its <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> values are generally set
|
||
|
|
to the <span class="emph">initial</span> values of the parameters in the creating place,
|
||
|
|
except that the <span class="emph">current</span> values of the following parameters are
|
||
|
|
used: <span class="RktSym"><a href="collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-paths%29%29" class="RktValLink" data-pltdoc="x">current-library-collection-paths</a></span>,
|
||
|
|
<span class="RktSym"><a href="collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-links%29%29" class="RktValLink" data-pltdoc="x">current-library-collection-links</a></span>, and
|
||
|
|
<span class="RktSym"><a href="eval.html#%28def._%28%28quote._~23~25kernel%29._current-compiled-file-roots%29%29" class="RktValLink" data-pltdoc="x">current-compiled-file-roots</a></span>.</p><p>A newly created place is registered with the <a href="eval-model.html#%28tech._current._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">current custodian</span></a>,
|
||
|
|
so that the place is terminated when the custodian is shut down.</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""places-api"">11.5.1<tt> </tt><a name="(part._places-api)"></a>Using Places</h5><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-enabled~3f))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-enabled~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-enabled?</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if Racket is configured so that
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span> and <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span> create places that can run
|
||
|
|
in parallel, <span class="RktVal">#f</span> if <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span> and <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span>
|
||
|
|
are simulated using <span class="RktSym"><a href="threads.html#%28def._%28%28quote._~23~25kernel%29._thread%29%29" class="RktValLink" data-pltdoc="x">thread</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place~3f))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">place?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">v</span> is a <a name="(tech._place._descriptor)"></a><span style="font-style: italic">place descriptor</span>
|
||
|
|
value, <span class="RktVal">#f</span> otherwise. Every <a href="places.html#%28tech._place._descriptor%29" class="techoutside" data-pltdoc="x"><span class="techinside">place descriptor</span></a>
|
||
|
|
is also a <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-channel~3f))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-channel?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">v</span> is <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a>,
|
||
|
|
<span class="RktVal">#f</span> otherwise.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._dynamic-place))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValDef RktValLink" data-pltdoc="x">dynamic-place</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">module-path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">start-name</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:at</span><span class="hspace"> </span><span class="RktVar">location</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:named</span><span class="hspace"> </span><span class="RktVar">named</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">module-path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._module-path~3f%29%29" class="RktValLink" data-pltdoc="x">module-path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">start-name</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="symbols.html#%28def._%28%28quote._~23~25kernel%29._symbol~3f%29%29" class="RktValLink" data-pltdoc="x">symbol?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">location</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="R
|
||
|
|
<span class="RktVar">module-path</span> and <span class="RktVar">start-name</span>. The result is a
|
||
|
|
<a href="places.html#%28tech._place._descriptor%29" class="techoutside" data-pltdoc="x"><span class="techinside">place descriptor</span></a> value that represents the new parallel task;
|
||
|
|
the place descriptor is returned immediately. The place descriptor
|
||
|
|
value is also a <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a> that permits communication with
|
||
|
|
the place.</div></p><p>The module indicated by <span class="RktVar">module-path</span> must export a function
|
||
|
|
with the name <span class="RktVar">start-name</span>. The function must accept a single
|
||
|
|
argument, which is a <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channel</span></a> that corresponds to the
|
||
|
|
other end of communication for the <a href="places.html#%28tech._place._descriptor%29" class="techoutside" data-pltdoc="x"><span class="techinside">place descriptor</span></a> returned
|
||
|
|
by <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span>.</p><p>If <span class="RktVar">location</span> is provided, it must be a <a href="places.html#%28tech._place._location%29" class="techoutside" data-pltdoc="x"><span class="techinside">place location</span></a>,
|
||
|
|
such as a distributed places node produced by <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=distributed-places&rel=index.html%23%2528def._%2528%2528lib._racket%252Fplace%252Fdistributed..rkt%2529._create-place-node%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">create-place-node</a></span>.</p><p>When the <a href="places.html#%28tech._place%29" class="techoutside" data-pltdoc="x"><span class="techinside">place</span></a> is created, the initial <a href="Exiting.html#%28tech._exit._handler%29" class="techoutside" data-pltdoc="x"><span class="techinside">exit handler</span></a>
|
||
|
|
terminates the place, using the argument to the exit handler as the
|
||
|
|
place’s <a name="(tech._completion._value)"></a><span style="font-style: italic">completion value</span>. Use <span class="RktPn">(</span><span class="RktSym"><a href="Exiting.html#%28def._%28%28quote._~23~25kernel%29._exit%29%29" class="RktValLink" data-pltdoc="x">exit</a></span><span class="stt"> </span><span class="RktVar">v</span><span class="RktPn">)</span> to
|
||
|
|
immediately terminate a place with the completion value
|
||
|
|
<span class="RktVar">v</span>. Since a completion value is limited to an exact integer
|
||
|
|
between <span class="RktVal">0</span> and <span class="RktVal">255</span>, any other value for <span class="RktSym">v</span>
|
||
|
|
is converted to <span class="RktVal">0</span>.</p><p>If the function indicated by <span class="RktVar">module-path</span> and
|
||
|
|
<span class="RktVar">start-name</span> returns, then the place terminates with the
|
||
|
|
<a href="places.html#%28tech._completion._value%29" class="techoutside" data-pltdoc="x"><span class="techinside">completion value</span></a> <span class="RktVal">0</span>.</p><p>In the created place, the <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29" class="RktValLink" data-pltdoc="x">current-input-port</a></span> parameter is
|
||
|
|
set to an empty input port, while the values of the
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29" class="RktValLink" data-pltdoc="x">current-output-port</a></span> and <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29" class="RktValLink" data-pltdoc="x">current-error-port</a></span>
|
||
|
|
parameters are connected to the current ports in the creating place.
|
||
|
|
If the output ports in the creating place are <a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream
|
||
|
|
ports</span></a>, then the connected ports in the created place share the
|
||
|
|
underlying streams, otherwise a <a href="eval-model.html#%28tech._thread%29" class="techoutside" data-pltdoc="x"><span class="techinside">thread</span></a> in the creating place
|
||
|
|
pumps bytes from the created place’s ports to the current ports in the
|
||
|
|
creating place.</p><p>Most <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameters</span></a> in the created place have their original
|
||
|
|
initial values, but the created place inherits the creating place’s
|
||
|
|
values for the following parameters: <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span>,
|
||
|
|
<span class="RktSym"><a href="collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-paths%29%29" class="RktValLink" data-pltdoc="x">current-library-collection-paths</a></span>,
|
||
|
|
<span class="RktSym"><a href="collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-links%29%29" class="RktValLink" data-pltdoc="x">current-library-collection-links</a></span>,
|
||
|
|
and <span class="RktSym"><a href="eval.html#%28def._%28%28quote._~23~25kernel%29._current-compiled-file-roots%29%29" class="RktValLink" data-pltdoc="x">current-compiled-file-roots</a></span>.</p><p>The <span class="RktVar">module-path</span> argument must not be a module path of the
|
||
|
|
form <span class="RktPn">(</span><span class="RktSym"><a href="quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">quote</a></span><span class="stt"> </span><span class="RktVar">sym</span><span class="RktPn">)</span> unless the module is predefined (see
|
||
|
|
<span class="RktSym"><a href="Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._module-predefined~3f%29%29" class="RktValLink" data-pltdoc="x">module-predefined?</a></span>).</p><p>The <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span> binding is protected in the sense of
|
||
|
|
<span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._protect-out%29%29" class="RktStxLink" data-pltdoc="x">protect-out</a></span>, so access to this operation can be prevented
|
||
|
|
by adjusting the code inspector (see <a href="modprotect.html" data-pltdoc="x">Code Inspectors</a>).</p><p class="SHistory">Changed in version 8.2.0.7 of package <span class="stt">base</span>: Changed created place to inherit
|
||
|
|
the creating place’s <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span>
|
||
|
|
value.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._dynamic-place*))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">dynamic-place*</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">module-path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">start-name</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:in</span><span class="hspace"> </span><span class="RktVar">in</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:out</span><span class="hspace"> </span><span class="RktVar">out</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:err</span><span class="hspace"> </span><span class="RktVar">err</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><table cellspacing="0" cellpadding="0"><tr><td><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._output-port~3f%29%29" class="RktValLink" data-pltdoc="x">output-port?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._input-port~3f%29%29" class="RktValLink" data-pltdoc="x">input-port?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn"
|
||
|
|
place’s ports, and returns a created port when <span class="RktVal">#f</span> is
|
||
|
|
supplied for a port. The <span class="RktVar">in</span>, <span class="RktVar">out</span>, and
|
||
|
|
<span class="RktVar">err</span> ports are connected to the <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29" class="RktValLink" data-pltdoc="x">current-input-port</a></span>,
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29" class="RktValLink" data-pltdoc="x">current-output-port</a></span>, and <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29" class="RktValLink" data-pltdoc="x">current-error-port</a></span> ports,
|
||
|
|
respectively, for the
|
||
|
|
<a href="places.html#%28tech._place%29" class="techoutside" data-pltdoc="x"><span class="techinside">place</span></a>. Any of the ports can be <span class="RktVal">#f</span>, in which case a
|
||
|
|
<a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream port</span></a> (for an operating-system pipe)
|
||
|
|
is created and returned by <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span>. The
|
||
|
|
<span class="RktVar">err</span> argument can be <span class="RktVal">'</span><span class="RktVal">stdout</span>, in which case the
|
||
|
|
same <a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream port</span></a> or that is supplied as standard
|
||
|
|
output is also used for standard error. For each port or
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">stdout</span> that is provided, no pipe is created and the
|
||
|
|
corresponding returned value is <span class="RktVal">#f</span>.</div></p><p>The caller of <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span> is responsible for closing all
|
||
|
|
returned ports; none are closed automatically.</p><p>The <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span> procedure returns four values:</p><ul><li><p>a place descriptor value representing the created place;</p></li><li><p>an output port piped to the place’s standard input, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">in</span> was a port;</p></li><li><p>an input port piped from the place’s standard output, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">out</span> was a port;</p></li><li><p>an input port piped from the place’s standard error, or
|
||
|
|
<span class="RktVal">#f</span> if <span class="RktVar">err</span> was a port or <span class="RktVal">'</span><span class="RktVal">stdout</span>.</p></li></ul><p>The <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span> binding is protected in the same way as
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-wait))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-wait%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-wait</a></span></span><span class="hspace"> </span><span class="RktVar">p</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-integer?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">p</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns the <a href="places.html#%28tech._completion._value%29" class="techoutside" data-pltdoc="x"><span class="techinside">completion value</span></a> of the place indicated by <span class="RktVar">p</span>,
|
||
|
|
blocking until the place has terminated.</div></p><p>If any pumping threads were created to connect a
|
||
|
|
non-<a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream port</span></a> to the ports in the place for <span class="RktVar">p</span>
|
||
|
|
(see <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>), <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-wait%29%29" class="RktValLink" data-pltdoc="x">place-wait</a></span> returns only when
|
||
|
|
the pumping threads have completed. </p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-dead-evt))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-dead-evt%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-dead-evt</a></span></span><span class="hspace"> </span><span class="RktVar">p</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="sync.html#%28def._%28%28quote._~23~25kernel%29._evt~3f%29%29" class="RktValLink" data-pltdoc="x">evt?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">p</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a> (see <a href="sync.html" data-pltdoc="x">Events</a>) that is
|
||
|
|
<a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> if and only if <span class="RktVar">p</span> has terminated.
|
||
|
|
The <a href="sync.html#%28tech._synchronization._result%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronization result</span></a> of a place-dead event is the place-dead event itself.</div></p><p>If any pumping threads were created to connect a non-<a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream
|
||
|
|
port</span></a> to the ports in the place for <span class="RktVar">p</span> (see
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>), the event returned by
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-dead-evt%29%29" class="RktValLink" data-pltdoc="x">place-dead-evt</a></span> may become ready even if a pumping thread is
|
||
|
|
still running.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-kill))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-kill%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-kill</a></span></span><span class="hspace"> </span><span class="RktVar">p</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">p</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Immediately terminates the place, setting the place’s
|
||
|
|
<a href="places.html#%28tech._completion._value%29" class="techoutside" data-pltdoc="x"><span class="techinside">completion value</span></a> to <span class="RktVal">1</span> if the place does not have a
|
||
|
|
completion value already.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-break))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-break%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-break</a></span></span><span class="hspace"> </span><span class="RktVar">p</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">kind</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">p</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place~3f%29%29" class="RktValLink" data-pltdoc="x">place?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">kind</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">hang-up</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">terminate</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Sends the main thread of place <span class="RktVar">p</span> a break; see <a href="breakhandler.html" data-pltdoc="x">Breaks</a>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-channel))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-channel</a></span></span><span class="RktPn"></span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><table cellspacing="0" cellpadding="0"><tr><td><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValLink" data-pltdoc="x">place-channel?</a></span></td><td><span class="hspace"> </span></td><td><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValLink" data-pltdoc="x">place-channel?</a></span></td></tr></table></td></tr></table></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns two <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channels</span></a>. Data sent through the first
|
||
|
|
channel can be received through the second channel, and data sent
|
||
|
|
through the second channel can be received from the first.</div></p><p>Typically, one place channel is used by the current <a href="places.html#%28tech._place%29" class="techoutside" data-pltdoc="x"><span class="techinside">place</span></a> to
|
||
|
|
send messages to a destination <a href="places.html#%28tech._place%29" class="techoutside" data-pltdoc="x"><span class="techinside">place</span></a>; the other place channel
|
||
|
|
is sent to the destination <a href="places.html#%28tech._place%29" class="techoutside" data-pltdoc="x"><span class="techinside">place</span></a> (via an existing <a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place
|
||
|
|
channel</span></a>).</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-channel-put))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-channel-put</a></span></span><span class="hspace"> </span><span class="RktVar">pch</span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">pch</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValLink" data-pltdoc="x">place-channel?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValLink" data-pltdoc="x">place-message-allowed?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Sends a message <span class="RktVar">v</span> on channel <span class="RktVar">pch</span>. Since place channels
|
||
|
|
are asynchronous, <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29" class="RktValLink" data-pltdoc="x">place-channel-put</a></span> calls are non-blocking.</div></p><p>See <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValLink" data-pltdoc="x">place-message-allowed?</a></span> form information on automatic
|
||
|
|
coercions in <span class="RktVar">v</span>, such as converting a mutable string to an
|
||
|
|
immutable string.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-channel-get))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-get%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-channel-get</a></span></span><span class="hspace"> </span><span class="RktVar">pch</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValLink" data-pltdoc="x">place-message-allowed?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">pch</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValLink" data-pltdoc="x">place-channel?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns a message received on channel <span class="RktVar">pch</span>, blocking until a
|
||
|
|
message is available.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-channel-put/get))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%2Fget%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-channel-put/get</a></span></span><span class="hspace"> </span><span class="RktVar">pch</span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">pch</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel~3f%29%29" class="RktValLink" data-pltdoc="x">place-channel?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Sends an immutable message <span class="RktVar">v</span> on channel <span class="RktVar">pch</span> and then
|
||
|
|
waits for a message (perhaps a reply) on the same channel.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-message-allowed~3f))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-message-allowed?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">v</span> is allowed as a message on a place channel,
|
||
|
|
<span class="RktVal">#f</span> otherwise.</div></p><p>If <span class="RktPn">(</span><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-enabled~3f%29%29" class="RktValLink" data-pltdoc="x">place-enabled?</a></span><span class="RktPn">)</span> returns <span class="RktVal">#f</span>, then the result is
|
||
|
|
always <span class="RktVal">#t</span> and no conversions are performed on <span class="RktVar">v</span> as a
|
||
|
|
message. Otherwise, the following kinds of data are allowed as
|
||
|
|
messages:</p><ul><li><p><a href="numbers.html#%28tech._number%29" class="techoutside" data-pltdoc="x"><span class="techinside">numbers</span></a>, <a href="characters.html#%28tech._character%29" class="techoutside" data-pltdoc="x"><span class="techinside">characters</span></a>, <a href="booleans.html#%28tech._boolean%29" class="techoutside" data-pltdoc="x"><span class="techinside">booleans</span></a>, <a href="keywords.html#%28tech._keyword%29" class="techoutside" data-pltdoc="x"><span class="techinside">keywords</span></a>, and
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></span></a>;</p></li><li><p><a href="symbols.html#%28tech._symbol%29" class="techoutside" data-pltdoc="x"><span class="techinside">symbols</span></a>, where the <span class="RktSym"><a href="Equality.html#%28def._%28%28quote._~23~25kernel%29._eq~3f%29%29" class="RktValLink" data-pltdoc="x">eq?</a></span>ness of <a href="symbols.html#%28tech._uninterned%29" class="techoutside" data-pltdoc="x"><span class="techinside">uninterned</span></a>
|
||
|
|
symbols is preserved within a single message, but not across
|
||
|
|
messages;</p></li><li><p><a href="strings.html#%28tech._string%29" class="techoutside" data-pltdoc="x"><span class="techinside">strings</span></a> and <a href="bytestrings.html#%28tech._byte._string%29" class="techoutside" data-pltdoc="x"><span class="techinside">byte strings</span></a>, where mutable strings
|
||
|
|
and byte strings are automatically replaced by immutable
|
||
|
|
variants;</p></li><li><p><a href="pathutils.html#%28tech._path%29" class="techoutside" data-pltdoc="x"><span class="techinside">paths</span></a> (for any platform);</p></li><li><p><a href="pairs.html#%28tech._pair%29" class="techoutside" data-pltdoc="x"><span class="techinside">pairs</span></a>, <a href="pairs.html#%28tech._list%29" class="techoutside" data-pltdoc="x"><span class="techinside">lists</span></a>, <a href="boxes.html#%28tech._box%29" class="techoutside" data-pltdoc="x"><span class="techinside">box</span></a>es, <a href="vectors.html#%28tech._vector%29" class="techoutside" data-pltdoc="x"><span class="techinside">vectors</span></a>, and immutable
|
||
|
|
<a href="structures.html#%28tech._prefab%29" class="techoutside" data-pltdoc="x"><span class="techinside">prefab</span></a> structures containing message-allowed values,
|
||
|
|
where a mutable box is automatically replaced by an
|
||
|
|
immutable box, a mutable vector is automatically replaced by an
|
||
|
|
immutable vector and where <a href="chaperones.html#%28tech._impersonator%29" class="techoutside" data-pltdoc="x"><span class="techinside">impersonators</span></a> of boxes, vectors and
|
||
|
|
<a href="structures.html#%28tech._prefab%29" class="techoutside" data-pltdoc="x"><span class="techinside">prefab</span></a> structures are copied;</p></li><li><p><a href="hashtables.html#%28tech._hash._table%29" class="techoutside" data-pltdoc="x"><span class="techinside">hash tables</span></a> where mutable hash tables are automatically
|
||
|
|
replaced by immutable variants, and where a
|
||
|
|
hash table <a href="chaperones.html#%28tech._impersonator%29" class="techoutside" data-pltdoc="x"><span class="techinside">impersonator</span></a> is copied;</p></li><li><p><a href="places.html#%28tech._place._channel%29" class="techoutside" data-pltdoc="x"><span class="techinside">place channels</span></a>, where a <a href="places.html#%28tech._place._descriptor%29" class="techoutside" data-pltdoc="x"><span class="techinside">place descriptor</span></a> is
|
||
|
|
automatically replaced by a plain place channel;</p></li><li><p><a href="file-ports.html#%28tech._file._stream._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">file-stream ports</span></a> and <a href="tcp.html#%28tech._tcp._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">TCP ports</span></a>, where the
|
||
|
|
underlying representation (such as a file descriptor, socket,
|
||
|
|
or handle) is duplicated in the sending place and attached to
|
||
|
|
a fresh port in the receiving place;</p></li><li><p><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=foreign&rel=Pointer_Types.html%23%2528tech._c._pointer%2529&version=8.6" class="techoutside Sq" data-pltdoc="x"><span class="techinside">C
|
||
|
|
pointers</span></a> as created or accessed via <a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=foreign&rel=index.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">ffi/unsafe</span></a>; and</p></li><li><p>values produced by <span class="RktSym"><a href="flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._shared-flvector%29%29" class="RktValLink" data-pltdoc="x">shared-flvector</a></span>,
|
||
|
|
<span class="RktSym"><a href="flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._make-shared-flvector%29%29" class="RktValLink" data-pltdoc="x">make-shared-flvector</a></span>, <span class="RktSym"><a href="fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._shared-fxvector%29%29" class="RktValLink" data-pltdoc="x">shared-fxvector</a></span>,
|
||
|
|
<span class="RktSym"><a href="fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._make-shared-fxvector%29%29" class="RktValLink" data-pltdoc="x">make-shared-fxvector</a></span>, <span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._shared-bytes%29%29" class="RktValLink" data-pltdoc="x">shared-bytes</a></span>, and
|
||
|
|
<span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._make-shared-bytes%29%29" class="RktValLink" data-pltdoc="x">make-shared-bytes</a></span>.</p></li></ul><p class="SHistory">Changed in version 8.4.0.7 of package <span class="stt">base</span>: Include boxes in allowed messages.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/place..rkt)._prop~3aplace-location))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._prop~3aplace-location%29%29" class="RktValDef RktValLink" data-pltdoc="x">prop:place-location</a></span></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="structprops.html#%28def._%28%28quote._~23~25kernel%29._struct-type-property~3f%29%29" class="RktValLink" data-pltdoc="x">struct-type-property?</a></span></p></blockquote></td></tr></table></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._place-location~3f))"></a><span title="Provided from: racket/place, racket/place/dynamic, racket | Package: base"><span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-location~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">place-location?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="structprops.html#%28tech._structure._type._property%29" class="techoutside" data-pltdoc="x"><span class="techinside">structure type property</span></a> and associated predicate for
|
||
|
|
implementations of <a name="(tech._place._location)"></a><span style="font-style: italic">place locations</span>. The value of
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._prop~3aplace-location%29%29" class="RktValLink" data-pltdoc="x">prop:place-location</a></span> must be a procedure of four arguments:
|
||
|
|
the <a href="places.html#%28tech._place._location%29" class="techoutside" data-pltdoc="x"><span class="techinside">place location</span></a> itself, a module path, a symbol for the
|
||
|
|
start function exported by the module, and a place name (which can be
|
||
|
|
<span class="RktVal">#f</span> for an anonymous place).</div></p><p>A <a href="places.html#%28tech._place._location%29" class="techoutside" data-pltdoc="x"><span class="techinside">place location</span></a> can be passed as the <span class="RktPn">#:at</span> argument to
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>, which in turn simply calls the
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._prop~3aplace-location%29%29" class="RktValLink" data-pltdoc="x">prop:place-location</a></span> value of the <a href="places.html#%28tech._place._location%29" class="techoutside" data-pltdoc="x"><span class="techinside">place location</span></a>.</p><p>A distributed places note created with <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=distributed-places&rel=index.html%23%2528def._%2528%2528lib._racket%252Fplace%252Fdistributed..rkt%2529._create-place-node%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">create-place-node</a></span>
|
||
|
|
is an example of a <a href="places.html#%28tech._place._location%29" class="techoutside" data-pltdoc="x"><span class="techinside">place location</span></a>.</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""places-syntax"">11.5.2<tt> </tt><a name="(part._places-syntax)"></a>Syntactic Support for Using Places</h5><p>The bindings in this section are <span class="emph">not</span> provided by
|
||
|
|
<a href="places.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/place/dynamic</span></a>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/place..rkt)._place))"></a><span title="Provided from: racket/place | Package: base"><span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">place</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">body</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Creates a place that evaluates <span class="RktVar">body</span>
|
||
|
|
expressions with <span class="RktVar">id</span> bound to a place channel. The
|
||
|
|
<span class="RktVar">body</span>s close only over <span class="RktVar">id</span> plus the top-level
|
||
|
|
bindings of the enclosing module, because the
|
||
|
|
<span class="RktVar">body</span>s are lifted to a submodule.
|
||
|
|
The result of <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span> is a place descriptor,
|
||
|
|
like the result of <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>.</div></p><p>The generated submodule has the name <span class="RktSym">place-body-<span class="RktVar">n</span></span>
|
||
|
|
for an integer <span class="RktVar">n</span>, and the submodule exports a <span class="RktSym">main</span>
|
||
|
|
function that takes a place channel for the new place. The submodule
|
||
|
|
is not intended for use, however, except by the expansion of the
|
||
|
|
<span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span> form.</p><p>The <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span> binding is protected in the same way as
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><table cellspacing="0" cellpadding="0" class="RktBlk RForeground"><tr><td><span class="RktPn">(</span><a name="(form._((lib._racket/place..rkt)._place*))"></a><span title="Provided from: racket/place | Package: base"><span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2A%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">place*</a></span></span><span class="hspace"> </span><span class="RktVar">maybe-port</span><span class="hspace"> </span><span class="RktMeta">...</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">id</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">body</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="stt"> </span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="specgrammar"><tr><td align="right" valign="baseline"><span class="RktVar">maybe-port</span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">=</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td></td></tr></table></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">#:in</span><span class="hspace"> </span><span class="RktVar">in-expr</span></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">#:out</span><span class="hspace"> </span><span class="RktVar">out-expr</span></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">#:err</span><span class="hspace"> </span><span class="RktVar">err-expr</span></td></tr></table></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span>, but supports optional <span class="RktPn">#:in</span>, <span class="RktPn">#:out</span>,
|
||
|
|
and <span class="RktPn">#:err</span> expressions (at most one of each) to specify ports in the same way and
|
||
|
|
with the same defaults as <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span>. The result of
|
||
|
|
a <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2A%29%29" class="RktStxLink" data-pltdoc="x">place*</a></span> form is also the same as for <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29" class="RktValLink" data-pltdoc="x">dynamic-place*</a></span>.</div></p><p>The <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2A%29%29" class="RktStxLink" data-pltdoc="x">place*</a></span> binding is protected in the same way as
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29" class="RktValLink" data-pltdoc="x">dynamic-place</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/place..rkt)._place/context))"></a><span title="Provided from: racket/place | Package: base"><span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2Fcontext%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">place/context</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">body</span><span class="hspace"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="places.html#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29" class="RktStxLink" data-pltdoc="x">place</a></span>, but <span class="RktVar">body</span><span class="stt"> </span><span class="RktMeta"><a href="stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29" class="RktStxLink" data-pltdoc="x">...</a></span> may have free lexical
|
||
|
|
variables, which are automatically sent to the newly-created place.
|
||
|
|
Note that these variables must have values accepted by
|
||
|
|
<span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29" class="RktValLink" data-pltdoc="x">place-message-allowed?</a></span>, otherwise an <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29" class="RktValLink" data-pltdoc="x">exn:fail:contract</a></span> exception is raised.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/place..rkt)._processor-count))"></a><span title="Provided from: racket/place | Package: base"><span class="RktSym"><a href="futures.html#%28def._%28%28lib._racket%2Ffuture..rkt%29._processor-count%29%29" class="RktValDef RktValLink" data-pltdoc="x">processor-count</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-positive-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-positive-integer?</a></span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns the number of parallel computation units (e.g., processors or
|
||
|
|
cores) that are available on the current machine.</div></p><p>This is the same binding as available from <a href="futures.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/future</span></a>.</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""place-logging"">11.5.3<tt> </tt><a name="(part._place-logging)"></a>Places Logging</h5><p>Place events are reported to a logger named <span class="RktVal">'</span><span class="RktVal">place</span>.
|
||
|
|
In addition to its string message, each event logged for a place has
|
||
|
|
a data value that is an instance of a <span class="RktSym">place-event</span>
|
||
|
|
<a href="structures.html#%28tech._prefab%29" class="techoutside" data-pltdoc="x"><span class="techinside">prefab</span></a> structure:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29" class="RktStxLink" data-pltdoc="x">struct</a></span><span class="hspace"> </span><span class="RktSym">place-event</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">place-id</span><span class="hspace"> </span><span class="RktSym">action</span><span class="hspace"> </span><span class="RktSym">value</span><span class="hspace"> </span><span class="RktSym"><a href="time.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._time%29%29" class="RktStxLink" data-pltdoc="x">time</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">#:prefab</span><span class="RktPn">)</span></td></tr></table></blockquote><p>The <span class="RktSym">place-id</span> field is an exact integer that identifies a
|
||
|
|
place.</p><p>The <span class="RktSym"><a href="time.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._time%29%29" class="RktStxLink" data-pltdoc="x">time</a></span> field is an inexact number that represents time in
|
||
|
|
the same way as <span class="RktSym"><a href="time.html#%28def._%28%28quote._~23~25kernel%29._current-inexact-milliseconds%29%29" class="RktValLink" data-pltdoc="x">current-inexact-milliseconds</a></span>.</p><p>The <span class="RktSym">action</span> field is a symbol:</p><ul><li><p><span class="RktVal">'</span><span class="RktVal">create</span>: a place was created. This event is logged in the
|
||
|
|
creating place, and the event’s <span class="RktSym">value</span> field has the
|
||
|
|
ID for the created place.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">reap</span>: a place that was previously created in the
|
||
|
|
current place has exited (and that fact has been detected,
|
||
|
|
possibly via <span class="RktSym"><a href="places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-wait%29%29" class="RktValLink" data-pltdoc="x">place-wait</a></span>). The event’s <span class="RktSym">value</span>
|
||
|
|
field has the ID for the exited place.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">enter</span>: a place has started, logged within the started
|
||
|
|
place. The event’s <span class="RktSym">value</span> field has <span class="RktVal">#f</span>.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">exit</span>: a place is exiting, logged within the exiting
|
||
|
|
place. The event’s <span class="RktSym">value</span> field has <span class="RktVal">#f</span>.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">put</span>: a place-channel message has been sent. The
|
||
|
|
event’s <span class="RktSym">value</span> field is a positive exact integer that
|
||
|
|
approximates the message’s size.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">get</span>: a place-channel message has been received. The
|
||
|
|
event’s <span class="RktSym">value</span> field is a positive exact integer that
|
||
|
|
approximates the message’s size.</p></li></ul><p class="SHistory">Changed in version 6.0.0.2 of package <span class="stt">base</span>: Added logging via <span class="RktVal">'</span><span class="RktVal">place</span>
|
||
|
|
and <span class="RktSym">place-event</span>.</p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" id="searchbox" type="text" tabindex="1" placeholder="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "8.6", "../");"/></form> <a href="https://docs.racket-lang.org/index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("8.6");">top</a><span class="tocsettoggle"> <a href="javascript:void(0);" title="show/hide table of contents" onclick="TocsetToggle();">contents</a></span></span><span class="navright"> <a href="futures.html" title="backward to "11.4 Futures"" data-pltdoc="x">← prev</a> <a href="concurrency.html" title="up to "11 Concurrency and Parallelism"" data-pltdoc="x">up</a> <a href="engine.html" title="forward to "11.6 Engines"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|