mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-05 19:00:33 -05:00
6 lines
17 KiB
HTML
6 lines
17 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Fiber (moonpool.Moonpool_fib.Fiber)</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">moonpool</a> » <a href="../index.html">Moonpool_fib</a> » Fiber</nav><header class="odoc-preamble"><h1>Module <code><span>Moonpool_fib.Fiber</span></code></h1><p>Fibers.</p><p>A fiber is a lightweight computation that runs cooperatively alongside other fibers. In the context of moonpool, fibers have additional properties:</p><ul><li>they run in a moonpool runner</li><li>they form a simple supervision tree, enabling a limited form of structured concurrency</li></ul></header><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-cancel_callback"><a href="#type-cancel_callback" class="anchor"></a><code><span><span class="keyword">type</span> cancel_callback</span><span> = <span><a href="../../Moonpool/Exn_bt/index.html#type-t">Moonpool.Exn_bt.t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>A callback used in case of cancellation</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a t</span></span></code></div><div class="spec-doc"><p>A fiber returning a value of type <code>'a</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-res"><a href="#val-res" class="anchor"></a><code><span><span class="keyword">val</span> res : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../../Moonpool/Fut/index.html#type-t">Moonpool.Fut.t</a></span></span></code></div><div class="spec-doc"><p>Future result of the fiber.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-callback"><a href="#type-callback" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a callback</span></span><span> = <span><span><span class="type-var">'a</span> <a href="../../Moonpool/Exn_bt/index.html#type-result">Moonpool.Exn_bt.result</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Callbacks that are called when a fiber is done.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-any"><a href="#type-any" class="anchor"></a><code><span><span class="keyword">type</span> any</span><span> = </span></code><ol><li id="type-any.Any" class="def variant constructor anchored"><a href="#type-any.Any" class="anchor"></a><code><span>| </span><span><span class="constructor">Any</span> : <span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span> <a href="#type-any">any</a></span></code></li></ol></div><div class="spec-doc"><p>Type erased fiber</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return"><a href="#val-return" class="anchor"></a><code><span><span class="keyword">val</span> return : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fail"><a href="#val-fail" class="anchor"></a><code><span><span class="keyword">val</span> fail : <span><a href="../../Moonpool/Exn_bt/index.html#type-t">Moonpool.Exn_bt.t</a> <span class="arrow">-></span></span> <span><span class="type-var">_</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-self"><a href="#val-self" class="anchor"></a><code><span><span class="keyword">val</span> self : <span>unit <span class="arrow">-></span></span> <a href="#type-any">any</a></span></code></div><div class="spec-doc"><p><code>self ()</code> is the current fiber. Must be run from inside a fiber.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Failure</code> <p>if not run from inside a fiber.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-peek"><a href="#val-peek" class="anchor"></a><code><span><span class="keyword">val</span> peek : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="../../Moonpool/Fut/index.html#type-or_error">Moonpool.Fut.or_error</a></span> option</span></span></code></div><div class="spec-doc"><p>Peek inside the future result</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_done"><a href="#val-is_done" class="anchor"></a><code><span><span class="keyword">val</span> is_done : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Has the fiber completed?</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_cancelled"><a href="#val-is_cancelled" class="anchor"></a><code><span><span class="keyword">val</span> is_cancelled : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Has the fiber completed with a failure?</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-is_success"><a href="#val-is_success" class="anchor"></a><code><span><span class="keyword">val</span> is_success : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Has the fiber completed with a value?</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-await"><a href="#val-await" class="anchor"></a><code><span><span class="keyword">val</span> await : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>await fib</code> is like <code>Fut.await (res fib)</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wait_block_exn"><a href="#val-wait_block_exn" class="anchor"></a><code><span><span class="keyword">val</span> wait_block_exn : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>wait_block_exn fib</code> is <code>Fut.wait_block_exn (res fib)</code>. <b>NOTE</b>: See <code>Fut.wait_block</code> for warnings about deadlocks.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wait_block"><a href="#val-wait_block" class="anchor"></a><code><span><span class="keyword">val</span> wait_block : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../../Moonpool/Fut/index.html#type-or_error">Moonpool.Fut.or_error</a></span></span></code></div><div class="spec-doc"><p><code>wait_block fib</code> is <code>Fut.wait_block (res fib)</code>. <b>NOTE</b>: See <code>Fut.wait_block</code> for warnings about deadlocks.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check_if_cancelled"><a href="#val-check_if_cancelled" class="anchor"></a><code><span><span class="keyword">val</span> check_if_cancelled : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Check if the current fiber is cancelled, in which case this raises. Must be run from inside a fiber.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>e</code> <p>if the current fiber is cancelled with exception <code>e</code></p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Failure</code> <p>if not run from a fiber.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-yield"><a href="#val-yield" class="anchor"></a><code><span><span class="keyword">val</span> yield : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Yield control to the scheduler from the current fiber.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Failure</code> <p>if not run from inside a fiber.</p></li></ul></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-cancel_handle"><a href="#type-cancel_handle" class="anchor"></a><code><span><span class="keyword">type</span> cancel_handle</span></code></div><div class="spec-doc"><p>An opaque handle for a single cancel callback in a fiber</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-add_on_cancel"><a href="#val-add_on_cancel" class="anchor"></a><code><span><span class="keyword">val</span> add_on_cancel : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-cancel_callback">cancel_callback</a> <span class="arrow">-></span></span> <a href="#type-cancel_handle">cancel_handle</a></span></code></div><div class="spec-doc"><p><code>add_on_cancel fib cb</code> adds <code>cb</code> to the list of cancel callbacks for <code>fib</code>. If <code>fib</code> is already cancelled, <code>cb</code> is called immediately.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-remove_on_cancel"><a href="#val-remove_on_cancel" class="anchor"></a><code><span><span class="keyword">val</span> remove_on_cancel : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-cancel_handle">cancel_handle</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>remove_on_cancel fib h</code> removes the cancel callback associated with handle <code>h</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_on_cancel"><a href="#val-with_on_cancel" class="anchor"></a><code><span><span class="keyword">val</span> with_on_cancel : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><a href="#type-cancel_callback">cancel_callback</a> <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>with_on_cancel fib cb (fun () -> <e>)</code> evaluates <code>e</code> in a scope in which, if the fiber <code>fib</code> is cancelled, <code>cb()</code> is called. If <code>e</code> returns without the fiber being cancelled, this callback is removed.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_on_self_cancel"><a href="#val-with_on_self_cancel" class="anchor"></a><code><span><span class="keyword">val</span> with_on_self_cancel : <span><a href="#type-cancel_callback">cancel_callback</a> <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>with_on_self_cancel cb f</code> calls <code>f()</code> in a scope where <code>cb</code> is added to the cancel callbacks of the current fiber; and <code>f()</code> terminates, <code>cb</code> is removed from the list.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_result"><a href="#val-on_result" class="anchor"></a><code><span><span class="keyword">val</span> on_result : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-callback">callback</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Wait for fiber to be done and call the callback with the result. If the fiber is done already then the callback is invoked immediately with its result.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-spawn_top"><a href="#val-spawn_top" class="anchor"></a><code><span><span class="keyword">val</span> spawn_top : <span><span class="label">on</span>:<a href="../../Moonpool/Runner/index.html#type-t">Moonpool.Runner.t</a> <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><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>spawn_top ~on f</code> spawns a new (toplevel) fiber onto the given runner. This fiber is not the child of any other fiber: its lifetime is only determined by the lifetime of <code>f()</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-spawn"><a href="#val-spawn" class="anchor"></a><code><span><span class="keyword">val</span> spawn : <span><span class="optlabel">?on</span>:<a href="../../Moonpool/Runner/index.html#type-t">Moonpool.Runner.t</a> <span class="arrow">-></span></span> <span><span class="optlabel">?protect</span>:bool <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><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>spawn ~protect f</code> spawns a sub-fiber <code>f_child</code> from a running fiber <code>parent</code>. The sub-fiber <code>f_child</code> is attached to the current fiber and fails if the current fiber <code>parent</code> fails.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">on</span> <p>if provided, start the fiber on the given runner. If not provided, use the parent's runner.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">protect</span> <p>if true, when <code>f_child</code> fails, it does not affect <code>parent</code>. If false, <code>f_child</code> failing also causes <code>parent</code> to fail (and therefore all other children of <code>parent</code>). Default is <code>true</code>.</p></li></ul><p>Must be run from inside a fiber.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Failure</code> <p>if not run from inside a fiber.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-spawn_ignore"><a href="#val-spawn_ignore" class="anchor"></a><code><span><span class="keyword">val</span> spawn_ignore :
|
||
<span><span class="optlabel">?on</span>:<a href="../../Moonpool/Runner/index.html#type-t">Moonpool.Runner.t</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?protect</span>:bool <span class="arrow">-></span></span>
|
||
<span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">_</span>)</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>spawn_ignore f</code> is <code>ignore (spawn f)</code>. The fiber will still affect termination of the parent, ie. the parent will exit only after this new fiber exits.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">on</span> <p>the optional runner to use, added since 0.7</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-spawn_top_ignore"><a href="#val-spawn_top_ignore" class="anchor"></a><code><span><span class="keyword">val</span> spawn_top_ignore : <span><span class="label">on</span>:<a href="../../Moonpool/Runner/index.html#type-t">Moonpool.Runner.t</a> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">_</span>)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Like <a href="#val-spawn_top"><code>spawn_top</code></a> but ignores the result.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.7</li></ul></div></div></div></body></html>
|