mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-06 03:05:30 -05:00
6 lines
8.1 KiB
HTML
6 lines
8.1 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Flock (picos_std.Picos_std_structured.Flock)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../../index.html">Index</a> » <a href="../../index.html">picos_std</a> » <a href="../index.html">Picos_std_structured</a> » Flock</nav><header class="odoc-preamble"><h1>Module <code><span>Picos_std_structured.Flock</span></code></h1><p>An implicit dynamic flock of fibers guaranteed to be joined at the end.</p><p>Flocks allow you to conveniently structure or delimit concurrency into nested scopes. After a flock returns or raises an exception, no fibers <a href="#val-fork" title="fork">forked</a> to the flock remain.</p><p>An unhandled exception, or error, within any fiber of the flock causes all of the fibers <a href="#val-fork" title="fork">forked</a> to the flock to be canceled and the flock to raise the error exception or <a href="../Control/index.html#exception-Errors" title="Control.Errors">error exceptions</a> raised by all of the fibers forked into the flock.</p><p>ℹ️ This is essentially a very thin convenience wrapper for an implicitly propagated <a href="../Bundle/index.html"><code>Bundle</code></a>.</p><p>⚠️ All of the operations in this module, except <a href="#val-join_after"><code>join_after</code></a>, raise the <code>Invalid_argument</code> exception in case they are called from outside of the dynamic multifiber scope of a flock established by calling <a href="#val-join_after"><code>join_after</code></a>.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec value anchored" id="val-join_after"><a href="#val-join_after" class="anchor"></a><code><span><span class="keyword">val</span> join_after :
|
||
<span><span class="optlabel">?callstack</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?on_return</span>:<span>[ `Terminate <span>| `Wait</span> ]</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>join_after scope</code> creates a new flock for fibers, calls <code>scope</code> after setting current flock to the new flock, and restores the previous flock, if any after <code>scope</code> exits. The flock will be implicitly propagated to all fibers <a href="#val-fork" title="fork">forked</a> into the flock. A call of <code>join_after</code> returns or raises only after <code>scope</code> has returned or raised and all <a href="#val-fork" title="fork">forked</a> fibers have terminated. If <code>scope</code> raises an exception, <a href="#val-error"><code>error</code></a> will be called.</p><p>The optional <code>on_return</code> argument specifies what to do when the scope returns normally. It defaults to <code>`Wait</code>, which means to just wait for all the fibers to terminate on their own. When explicitly specified as <code>~on_return:`Terminate</code>, then <a href="#val-terminate" title="terminate"><code>terminate ?callstack</code></a> will be called on return. This can be convenient, for example, when dealing with <a href="https://en.wikipedia.org/wiki/Daemon_(computing)">daemon</a> fibers.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-terminate"><a href="#val-terminate" class="anchor"></a><code><span><span class="keyword">val</span> terminate : <span><span class="optlabel">?callstack</span>:int <span class="arrow">-></span></span> <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>terminate ()</code> cancels all of the <a href="#val-fork" title="fork">forked</a> fibers using the <a href="../Control/index.html#exception-Terminate" title="Control.Terminate"><code>Terminate</code></a> exception. After <code>terminate</code> has been called, no new fibers can be forked to the current flock.</p><p>The optional <code>callstack</code> argument specifies the number of callstack entries to capture with the <a href="../Control/index.html#exception-Terminate" title="Control.Terminate"><code>Terminate</code></a> exception. The default is <code>0</code>.</p><p>ℹ️ Calling <code>terminate</code> at the end of a flock can be a convenient way to cancel any background fibers started by the flock.</p><p>ℹ️ Calling <code>terminate</code> does not raise the <a href="../Control/index.html#exception-Terminate" title="Control.Terminate"><code>Terminate</code></a> exception, but blocking operations after <code>terminate</code> will raise the exception to propagate cancelation unless <a href="../Control/index.html#val-protect" title="Control.protect">propagation of cancelation is forbidden</a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-terminate_after"><a href="#val-terminate_after" class="anchor"></a><code><span><span class="keyword">val</span> terminate_after : <span><span class="optlabel">?callstack</span>:int <span class="arrow">-></span></span> <span><span class="label">seconds</span>:float <span class="arrow">-></span></span> <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>terminate_after ~seconds ()</code> arranges to <a href="#val-terminate"><code>terminate</code></a> the current flock after the specified timeout in <code>seconds</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-error"><a href="#val-error" class="anchor"></a><code><span><span class="keyword">val</span> error : <span><span class="optlabel">?callstack</span>:int <span class="arrow">-></span></span> <span>exn <span class="arrow">-></span></span> <span><a href="../../../ocaml/Stdlib/Printexc/index.html#type-raw_backtrace">Stdlib.Printexc.raw_backtrace</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>error exn bt</code> first calls <a href="#val-terminate"><code>terminate</code></a> and then adds the exception with backtrace to the list of exceptions to be raised, unless the exception is the <a href="../Control/index.html#exception-Terminate" title="Control.Terminate"><code>Terminate</code></a> exception, which is not considered to signal an error by itself.</p><p>The optional <code>callstack</code> argument is passed to <a href="#val-terminate"><code>terminate</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fork_as_promise"><a href="#val-fork_as_promise" class="anchor"></a><code><span><span class="keyword">val</span> fork_as_promise : <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../Promise/index.html#type-t">Promise.t</a></span></span></code></div><div class="spec-doc"><p><code>fork_as_promise thunk</code> spawns a new fiber to the current flock that will run the given <code>thunk</code>. The result of the <code>thunk</code> will be written to the <a href="../Promise/index.html" title="Promise">promise</a>. If the <code>thunk</code> raises an exception, <a href="#val-error"><code>error</code></a> will be called with that exception.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fork"><a href="#val-fork" class="anchor"></a><code><span><span class="keyword">val</span> fork : <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>fork action</code> is equivalent to <a href="#val-fork_as_promise" title="fork_as_promise"><code>fork_as_promise action |> ignore</code></a>.</p></div></div></div></body></html>
|