/usr/share/doc/racket/reference/futures.html is in racket-doc 6.7-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | <!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"/><title>11.4 Futures</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"><span style="font-weight: bold">The Racket Reference</span></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><td align="right">18 </td><td><a href="running.html" class="tocviewlink" data-pltdoc="x">Running Racket</a></td></tr><tr><td align="right"></td><td><a href="doc-bibliography.html" class="tocviewlink" data-pltdoc="x">Bibliography</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">▼</a></td><td>11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr></table><div class="tocviewsublist" style="display: block;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">11.1 </td><td><a href="threads.html" class="tocviewlink" data-pltdoc="x">Threads</a></td></tr><tr><td align="right">11.2 </td><td><a href="all-sync.html" class="tocviewlink" data-pltdoc="x">Synchronization</a></td></tr><tr><td align="right">11.3 </td><td><a href="thread-local-storage.html" class="tocviewlink" data-pltdoc="x">Thread-<wbr></wbr>Local Storage</a></td></tr><tr><td align="right">11.4 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Futures</a></td></tr><tr><td align="right">11.5 </td><td><a href="places.html" class="tocviewlink" data-pltdoc="x">Places</a></td></tr><tr><td align="right">11.6 </td><td><a href="engine.html" class="tocviewlink" data-pltdoc="x">Engines</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_2");">►</a></td><td>11.4 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Futures</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_2"><table cellspacing="0" cellpadding="0"><tr><td align="right">11.4.1 </td><td><a href="#%28part._.Creating_and_.Touching_.Futures%29" class="tocviewlink" data-pltdoc="x">Creating and Touching Futures</a></td></tr><tr><td align="right">11.4.2 </td><td><a href="#%28part._.Future_.Semaphores%29" class="tocviewlink" data-pltdoc="x">Future Semaphores</a></td></tr><tr><td align="right">11.4.3 </td><td><a href="#%28part._future-logging%29" class="tocviewlink" data-pltdoc="x">Future Performance Logging</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">11.4.1<tt> </tt></span><a href="#%28part._.Creating_and_.Touching_.Futures%29" class="tocsubseclink" data-pltdoc="x">Creating and Touching Futures</a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">future</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">touch</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._futures-enabled~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">futures-<wbr></wbr>enabled?</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._current-future%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">current-<wbr></wbr>future</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">future?</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._would-be-future%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">would-<wbr></wbr>be-<wbr></wbr>future</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._processor-count%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">processor-<wbr></wbr>count</span></span></a></td></tr><tr><td><a href="#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2Fasync%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">for/<span class="mywbr"> </span>async</span></span></a></td></tr><tr><td><a href="#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2A%2Fasync%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">for*/<span class="mywbr"> </span>async</span></span></a></td></tr><tr><td><span class="tocsublinknumber">11.4.2<tt> </tt></span><a href="#%28part._.Future_.Semaphores%29" class="tocsubseclink" data-pltdoc="x">Future Semaphores</a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._make-fsemaphore%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">make-<wbr></wbr>fsemaphore</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">fsemaphore?</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-post%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">fsemaphore-<wbr></wbr>post</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-wait%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">fsemaphore-<wbr></wbr>wait</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-try-wait~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">fsemaphore-<wbr></wbr>try-<wbr></wbr>wait?</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-count%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">fsemaphore-<wbr></wbr>count</span></span></a></td></tr><tr><td><span class="tocsublinknumber">11.4.3<tt> </tt></span><a href="#%28part._future-logging%29" class="tocsubseclink" data-pltdoc="x">Future Performance Logging</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.7", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.7");">top</a></span><span class="navright"> <a href="parameters.html" title="backward to "11.3.2 Parameters"" data-pltdoc="x">← prev</a> <a href="concurrency.html" title="up to "11 Concurrency and Parallelism"" data-pltdoc="x">up</a> <a href="places.html" title="forward to "11.5 Places"" data-pltdoc="x">next →</a></span> </div><h4 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""futures"">11.4<tt> </tt><a name="(part._futures)"></a><a name="(mod-path._racket/future)"></a>Futures</h4><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p><span class="imageleft"><img src="finger.png" alt="+" width="24" height="24"/></span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=parallelism.html%23%2528part._effective-futures%2529&version=6.7" class="Sq" data-pltdoc="x">Parallelism with Futures</a> in <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=index.html&version=6.7" class="Sq" data-pltdoc="x"><span style="font-weight: bold">The Racket Guide</span></a> introduces futures.</p></blockquote></blockquote></blockquote><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/future</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">base</span></span></td></tr></table></div><div class="SIntrapara">The bindings documented in this section are provided by the <a href="" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/future</span></a> and <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a> libraries, but not <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a>.</div></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>Currently, parallel support for <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> is enabled
by default for Windows, Linux x86/x86_64, and Mac OS X x86/x86_64. To
enable support for other platforms, use <span class="nobreak"><span class="stt">--enable-futures</span></span> with
<span class="stt">configure</span> when building Racket.</p></blockquote></blockquote></blockquote><p>The <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> and <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> functions from
<a href="" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/future</span></a> provide access to parallelism as supported
by the hardware and operating system. In contrast to <span class="RktSym"><a href="threads.html#%28def._%28%28quote._~23~25kernel%29._thread%29%29" class="RktValLink" data-pltdoc="x">thread</a></span>,
which provides concurrency for arbitrary computations without
parallelism, <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> provides parallelism for limited
computations. A <a name="(tech._future)"></a><span style="font-style: italic">future</span> executes its work in parallel (assuming that
support for parallelism is available) until it detects an attempt to
perform an operation that is too complex for the system to run safely in
parallel. Similarly, work in a future is suspended if it depends in some
way on the current continuation, such as raising an exception. A
suspended computation for a future is resumed when <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> is
applied to the future.</p><p>“Safe” parallel execution of a future means that all operations
provided by the system must be able to enforce contracts and produce
results as documented. “Safe” does not preclude concurrent access to
mutable data that is visible in the program. For example, a computation
in a future might use <span class="RktSym"><a href="set_.html#%28form._%28%28quote._~23~25kernel%29._set%21%29%29" class="RktStxLink" data-pltdoc="x">set!</a></span> to modify a shared variable, in
which case concurrent assignment to the variable can be visible in other
futures and threads. Furthermore, guarantees about the visibility of
effects and ordering are determined by the operating system and
hardware—<wbr></wbr>which rarely support, for example, the guarantee of
sequential consistency that is provided for <span class="RktSym"><a href="threads.html#%28def._%28%28quote._~23~25kernel%29._thread%29%29" class="RktValLink" data-pltdoc="x">thread</a></span>-based
concurrency. At the same time, operations that seem obviously safe may
have a complex enough implementation internally that they cannot run in
parallel. See also <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=parallelism.html%23%2528part._effective-futures%2529&version=6.7" class="Sq" data-pltdoc="x">Parallelism with Futures</a> in <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=index.html&version=6.7" class="Sq" data-pltdoc="x"><span style="font-weight: bold">The Racket Guide</span></a>.</p><p>A future never runs in parallel if all of the <a href="eval-model.html#%28tech._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">custodians</span></a> that
allow its creating thread to run are shut down. Such futures can
execute through a call to <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span>, however.</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Creating_and_Touching_Futures"">11.4.1<tt> </tt><a name="(part._.Creating_and_.Touching_.Futures)"></a>Creating and Touching Futures</h5><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>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/future..rkt)._future))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValDef RktValLink" data-pltdoc="x">future</a></span></span><span class="hspace"> </span><span class="RktVar">thunk</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="RktValLink" data-pltdoc="x">future?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">thunk</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span></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/future..rkt)._touch))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValDef RktValLink" data-pltdoc="x">touch</a></span></span><span class="hspace"> </span><span class="RktVar">f</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">f</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="RktValLink" data-pltdoc="x">future?</a></span></td></tr></table></td></tr></table></blockquote></div><div class="SIntrapara">The <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> procedure returns a future value that encapsulates
<span class="RktVar">thunk</span>. The <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> function forces the evaluation of
the <span class="RktVar">thunk</span> inside the given future, returning the values
produced by <span class="RktVar">thunk</span>. After <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> forces the evaluation
of a <span class="RktVar">thunk</span>, the resulting values are retained by the future
in place of <span class="RktVar">thunk</span>, and additional <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span>es of the
future return those values.</div></p><p>Between a call to <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> and <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> for a given
future, the given <span class="RktVar">thunk</span> may run speculatively in parallel to
other computations, as described above.</p><p><div class="SIntrapara">Example:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><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="RktVar">f</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2B%29%29" class="RktValLink" data-pltdoc="x">+</a></span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktPn">)</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="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2B%29%29" class="RktValLink" data-pltdoc="x">+</a></span><span class="hspace"> </span><span class="RktVal">3</span><span class="hspace"> </span><span class="RktVal">4</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span><span class="hspace"> </span><span class="RktVar">f</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><p><span class="RktRes">'(7 3)</span></p></td></tr></table></blockquote></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/future..rkt)._futures-enabled~3f))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._futures-enabled~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">futures-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 whether parallel support for futures is enabled
in the current Racket configuration.</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/future..rkt)._current-future))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._current-future%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-future</a></span></span><span class="RktPn"></span><span class="RktPn">)</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="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="RktValLink" data-pltdoc="x">future?</a></span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns the descriptor of the future whose thunk execution is the
current continuation. If a future thunk itself uses <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span>,
future-thunk executions can be nested, in which case the descriptor of
the most immediately executing future is returned. If the current
continuation is not a future-thunk execution, the result is
<span class="RktVal">#f</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/future..rkt)._future~3f))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">future?</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 future value, <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><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/future..rkt)._would-be-future))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._would-be-future%29%29" class="RktValDef RktValLink" data-pltdoc="x">would-be-future</a></span></span><span class="hspace"> </span><span class="RktVar">thunk</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future~3f%29%29" class="RktValLink" data-pltdoc="x">future?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">thunk</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Returns a future that never runs in parallel, but that consistently
logs all potentially “unsafe” operations during the execution of
the future’s thunk (i.e., operations that interfere with parallel
execution).</div></p><p>With a normal future, certain circumstances might prevent the logging
of unsafe operations. For example, when executed with debug-level logging,</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </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="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">"hello1"</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">"hello2"</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">"hello3"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote><p>might log three messages, one for each <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span>
invocation. However, if the <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> is performed before the future
has a chance to start running in parallel, the future thunk evaluates
in the same manner as any ordinary thunk, and no unsafe operations
are logged. Replacing <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span> with <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._would-be-future%29%29" class="RktValLink" data-pltdoc="x">would-be-future</a></span>
ensures the logging of all three calls to <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</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/future..rkt)._processor-count))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%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><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>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/future..rkt)._for/async))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2Fasync%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">for/async</a></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktVar">for-clause</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</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></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><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/future..rkt)._for*/async))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2A%2Fasync%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">for*/async</a></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktVar">for-clause</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</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></td></tr></table></blockquote></div><div class="SIntrapara">Like <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> and <span class="RktSym"><a href="for.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for%2A%29%29" class="RktStxLink" data-pltdoc="x">for*</a></span>, but each iteration of the
<span class="RktVar">body</span> is executed in a separate <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29" class="RktValLink" data-pltdoc="x">future</a></span>, and
the futures may be <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span>ed in any order.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Future_Semaphores"">11.4.2<tt> </tt><a name="(part._.Future_.Semaphores)"></a>Future Semaphores</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/future..rkt)._make-fsemaphore))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._make-fsemaphore%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-fsemaphore</a></span></span><span class="hspace"> </span><span class="RktVar">init</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">init</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Creates and returns a new <a name="(tech._future._semaphore)"></a><span style="font-style: italic">future semaphore</span> with the
counter initially set to <span class="RktVar">init</span>.</div></p><p>A future semaphore is similar to a plain <a href="semaphore.html#%28tech._semaphore%29" class="techoutside" data-pltdoc="x"><span class="techinside">semaphore</span></a>, but
future-semaphore operations can be performed safely in parallel (to synchronize
parallel computations). In contrast, operations on plain <a href="semaphore.html#%28tech._semaphore%29" class="techoutside" data-pltdoc="x"><span class="techinside">semaphores</span></a>
are not safe to perform in parallel, and they therefore prevent
a computation from continuing in parallel.</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/future..rkt)._fsemaphore~3f))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">fsemaphore?</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 an <a href="#%28tech._future._semaphore%29" class="techoutside" data-pltdoc="x"><span class="techinside">future semaphore</span></a>
value, <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><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/future..rkt)._fsemaphore-post))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-post%29%29" class="RktValDef RktValLink" data-pltdoc="x">fsemaphore-post</a></span></span><span class="hspace"> </span><span class="RktVar">fsema</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">fsema</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Increments the <a href="#%28tech._future._semaphore%29" class="techoutside" data-pltdoc="x"><span class="techinside">future semaphore</span></a>’s internal counter and
returns <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></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/future..rkt)._fsemaphore-wait))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-wait%29%29" class="RktValDef RktValLink" data-pltdoc="x">fsemaphore-wait</a></span></span><span class="hspace"> </span><span class="RktVar">fsema</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">fsema</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Blocks until the internal counter for <span class="RktVar">fsema</span> is non-zero.
When the counter is non-zero, it is decremented and
<span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-wait%29%29" class="RktValLink" data-pltdoc="x">fsemaphore-wait</a></span> returns <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></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/future..rkt)._fsemaphore-try-wait~3f))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-try-wait~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">fsemaphore-try-wait?</a></span></span><span class="hspace"> </span><span class="RktVar">fsema</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">fsema</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-wait%29%29" class="RktValLink" data-pltdoc="x">fsemaphore-wait</a></span>, but <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-try-wait~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore-try-wait?</a></span>
never blocks execution. If <span class="RktVar">fsema</span>’s internal counter is zero,
<span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-try-wait~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore-try-wait?</a></span> returns <span class="RktVal">#f</span> immediately without
decrementing the counter. If <span class="RktVar">fsema</span>’s counter is positive, it
is decremented and <span class="RktVal">#t</span> is returned.</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/future..rkt)._fsemaphore-count))"></a><span title="Provided from: racket/future, racket | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-count%29%29" class="RktValDef RktValLink" data-pltdoc="x">fsemaphore-count</a></span></span><span class="hspace"> </span><span class="RktVar">fsema</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-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">fsema</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore~3f%29%29" class="RktValLink" data-pltdoc="x">fsemaphore?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVar">fsema</span>’s current internal counter value.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""future-logging"">11.4.3<tt> </tt><a name="(part._future-logging)"></a>Future Performance Logging</h5><p>Racket traces use logging (see <a href="logging.html" data-pltdoc="x">Logging</a>) extensively to
report information about how futures are evaluated. Logging output is
useful for debugging the performance of programs that use futures.</p><p>Though textual log output can be viewed directly (or retrieved in
code via <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=future-visualizer&rel=futures-trace.html%23%2528form._%2528%2528lib._future-visualizer%252Ftrace..rkt%2529._trace-futures%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">trace-futures</a></span>), it is much
easier to use the graphical profiler tool provided by
<a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=future-visualizer&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">future-visualizer</span></a>.</p><p>Future events are logged with the topic <span class="RktVal">'</span><span class="RktVal">future</span>.
In addition to its string message, each event logged for a future has
a data value that is an instance of a <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=future-visualizer&rel=futures-trace.html%23%2528def._%2528%2528lib._future-visualizer%252Ftrace..rkt%2529._future-event%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">future-event</a></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"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=future-visualizer&rel=futures-trace.html%23%2528def._%2528%2528lib._future-visualizer%252Ftrace..rkt%2529._future-event%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">future-event</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">future-id</span><span class="hspace"> </span><span class="RktSym">proc-id</span><span class="hspace"> </span><span class="RktSym">action</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="hspace"> </span><span class="RktSym">prim-name</span><span class="hspace"> </span><span class="RktSym">user-data</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">future-id</span> field is an exact integer that identifies a
future, or it is <span class="RktVal">#f</span> when <span class="RktSym">action</span> is
<span class="RktVal">'</span><span class="RktVal">missing</span>. The <span class="RktSym">future-id</span> field is particularly useful
for correlating logged events.</p><p>The <span class="RktSym">proc-id</span> fields is an exact, non-negative integer that
identifies a parallel process. Process 0 is the main Racket process,
where all expressions other than future thunks evaluate.</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 future was created.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">complete</span>: a future’s thunk evaluated successfully, so
that <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> will produce a value for the future
immediately.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">start-work</span> and <span class="RktVal">'</span><span class="RktVal">end-work</span>: a particular
process started and ended working on a particular future.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">start-0-work</span>: like <span class="RktVal">'</span><span class="RktVal">start-work</span>, but for a
future thunk that for some structural reason could not be
started in a process other than 0 (e.g., the thunk requires too
much local storage to start).</p></li><li><p><span class="RktVal">'</span><span class="RktVal">start-overflow-work</span>: like <span class="RktVal">'</span><span class="RktVal">start-work</span>, where
the future thunk’s work was previously stopped due to an
internal stack overflow.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">sync</span>: blocking (processes other than 0) or initiation
of handing (process 0) for an “unsafe” operation in a future
thunk’s evaluation; the operation must run in process 0.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">block</span>: like <span class="RktVal">'</span><span class="RktVal">sync</span>, but for a part of
evaluation that must be delayed until the future is
<span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span>ed, because the evaluation may depend on the
current continuation.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">touch</span> (never in process 0): like <span class="RktVal">'</span><span class="RktVal">sync</span> or
<span class="RktVal">'</span><span class="RktVal">block</span>, but for a <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> operation within a
future thunk.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">overflow</span> (never in process 0): like <span class="RktVal">'</span><span class="RktVal">sync</span> or
<span class="RktVal">'</span><span class="RktVal">block</span>, but for the case that a process encountered an
internal stack overflow while evaluating a future thunk.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">result</span> or <span class="RktVal">'</span><span class="RktVal">abort</span>: waiting or handling for
<span class="RktVal">'</span><span class="RktVal">sync</span>, <span class="RktVal">'</span><span class="RktVal">block</span>, or <span class="RktVal">'</span><span class="RktVal">touch</span> ended with
a value or an error, respectively.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">suspend</span> (never in process 0): a process blocked by
<span class="RktVal">'</span><span class="RktVal">sync</span>, <span class="RktVal">'</span><span class="RktVal">block</span>, or <span class="RktVal">'</span><span class="RktVal">touch</span> abandoned
evaluation of a future; some other process may pick up the
future later.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">touch-pause</span> and <span class="RktVal">'</span><span class="RktVal">touch-resume</span> (in process 0,
only): waiting in <span class="RktSym"><a href="#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29" class="RktValLink" data-pltdoc="x">touch</a></span> for a future whose thunk is
being evaluated in another process.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">missing</span>: one or more events for the process were lost
due to internal buffer limits before they could be reported,
and the <span class="RktSym">time-id</span> field reports an upper limit on the time
of the missing events; this kind of event is rare.</p></li></ul><p>Assuming no <span class="RktVal">'</span><span class="RktVal">missing</span> events, then <span class="RktVal">'</span><span class="RktVal">start-work</span>,
<span class="RktVal">'</span><span class="RktVal">start-0-work</span>, <span class="RktVal">'</span><span class="RktVal">start-overflow-work</span> is always paired with <span class="RktVal">'</span><span class="RktVal">end-work</span>;
<span class="RktVal">'</span><span class="RktVal">sync</span>, <span class="RktVal">'</span><span class="RktVal">block</span>, and <span class="RktVal">'</span><span class="RktVal">touch</span> are always paired
with <span class="RktVal">'</span><span class="RktVal">result</span>, <span class="RktVal">'</span><span class="RktVal">abort</span>, or <span class="RktVal">'</span><span class="RktVal">suspend</span>; and
<span class="RktVal">'</span><span class="RktVal">touch-pause</span> is always paired with <span class="RktVal">'</span><span class="RktVal">touch-resume</span>.</p><p>In process 0, some event pairs can be nested within other event pairs:
<span class="RktVal">'</span><span class="RktVal">sync</span>, <span class="RktVal">'</span><span class="RktVal">block</span>, or <span class="RktVal">'</span><span class="RktVal">touch</span> with
<span class="RktVal">'</span><span class="RktVal">result</span> or <span class="RktVal">'</span><span class="RktVal">abort</span>; and <span class="RktVal">'</span><span class="RktVal">touch-pause</span> with
<span class="RktVal">'</span><span class="RktVal">touch-resume</span>.</p><p>An <span class="RktVal">'</span><span class="RktVal">block</span> in process 0 is generated when an unsafe operation
is handled. This type of event will contain a symbol in the
<span class="RktSym">unsafe-op-name</span> field that is the name of the operation. In all
other cases, this field contains <span class="RktVal">#f</span>.</p><p>The <span class="RktSym">prim-name</span> field will always be <span class="RktVal">#f</span> unless the event occurred
on process 0 and its <span class="RktSym">action</span> is either <span class="RktVal">'</span><span class="RktVal">block</span> or <span class="RktVal">'</span><span class="RktVal">sync</span>. If
these conditions are met, <span class="RktSym">prim-name</span> will contain the name
of the Racket primitive which required the future to synchronize with the runtime
thread (represented as a symbol).</p><p>The <span class="RktSym">user-data</span> field may take on a number of different
values depending on both the <span class="RktSym">action</span> and <span class="RktSym">prim-name</span> fields:</p><ul><li><p><span class="RktVal">'</span><span class="RktVal">touch</span> on process 0: contains the integer ID of the future
being touched.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">sync</span> and <span class="RktSym">prim-name</span> = <span class="RktSym">|allocate memory|</span>:
The size (in bytes) of the requested allocation.</p></li><li><p><span class="RktVal">'</span><span class="RktVal">sync</span> and <span class="RktSym">prim-name</span> = <span class="RktSym">jit_on_demand</span>:
The runtime thread is performing a JIT compilation on behalf of the
future <span class="RktSym">future-id</span>. The field contains the name of the function
being JIT compiled (as a symbol).</p></li><li><p><span class="RktVal">'</span><span class="RktVal">create</span>: A new future was created. The field contains the integer ID
of the newly created future.</p></li></ul><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.7", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.7");">top</a></span><span class="navright"> <a href="parameters.html" title="backward to "11.3.2 Parameters"" data-pltdoc="x">← prev</a> <a href="concurrency.html" title="up to "11 Concurrency and Parallelism"" data-pltdoc="x">up</a> <a href="places.html" title="forward to "11.5 Places"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|