mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-07 11:45:39 -05:00
17 lines
8.9 KiB
HTML
17 lines
8.9 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Control (picos_std.Picos_std_structured.Control)</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> » Control</nav><header class="odoc-preamble"><h1>Module <code><span>Picos_std_structured.Control</span></code></h1><p>Basic control operations and exceptions for structured concurrency.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec exception anchored" id="exception-Terminate"><a href="#exception-Terminate" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Terminate</span></span></code></div><div class="spec-doc"><p>An exception that is used to signal fibers, typically by canceling them, that they should terminate by letting the exception propagate.</p><p>ℹ️ Within <a href="../index.html" title="Picos_std_structured">this library</a>, the <code>Terminate</code> exception does not, by itself, indicate an error. Raising it inside a fiber forked within the structured concurrency constructs of this library simply causes the relevant part of the tree of fibers to be terminated.</p><p>⚠️ If <code>Terminate</code> is raised in the main fiber of a <a href="../Bundle/index.html"><code>Bundle</code></a>, and no other exceptions are raised within any fiber inside the bundle, the bundle will then, of course, raise the <code>Terminate</code> exception after all of the fibers have been terminated.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Errors"><a href="#exception-Errors" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Errors</span> <span class="keyword">of</span> <span><span>(exn * <a href="../../../ocaml/Stdlib/Printexc/index.html#type-raw_backtrace">Stdlib.Printexc.raw_backtrace</a>)</span> list</span></span></code></div><div class="spec-doc"><p>An exception that can be used to collect exceptions, typically indicating errors, from multiple fibers.</p><p>ℹ️ The <a href="#exception-Terminate"><code>Terminate</code></a> exception is not considered an error within <a href="../index.html" title="Picos_std_structured">this library</a> and the structuring constructs do not include it in the list of <code>Errors</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-raise_if_canceled"><a href="#val-raise_if_canceled" class="anchor"></a><code><span><span class="keyword">val</span> raise_if_canceled : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>raise_if_canceled ()</code> checks whether the current fiber has been canceled and if so raises the exception that the fiber was canceled with.</p><p>ℹ️ Within <a href="../index.html" title="Picos_std_structured">this library</a> fibers are canceled using the <a href="#exception-Terminate"><code>Terminate</code></a> exception.</p></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><code>yield ()</code> asks the current fiber to be rescheduled.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sleep"><a href="#val-sleep" class="anchor"></a><code><span><span class="keyword">val</span> sleep : <span><span class="label">seconds</span>:float <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>sleep ~seconds</code> suspends the current fiber for the specified number of <code>seconds</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-protect"><a href="#val-protect" class="anchor"></a><code><span><span class="keyword">val</span> protect : <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>protect thunk</code> forbids propagation of cancelation for the duration of <code>thunk ()</code>.</p><p>ℹ️ <a href="../../Picos_std_sync/index.html" title="Picos_std_sync">Many operations are cancelable</a>. In particular, anything that might suspend the current fiber to await for something should typically be cancelable. Operations that release resources may sometimes also be cancelable and <a href="../../Picos_std_finally/index.html#val-finally" title="Picos_std_finally.finally">calls of such operations should typically be protected</a> to ensure that resources will be properly released. Forbidding propagation of cancelation may also be required when a sequence of cancelable operations must be performed.</p><p>ℹ️ With the constructs provided by <a href="../index.html" title="Picos_std_structured">this library</a> it is not possible to prevent a fiber from being canceled, but it is possible for a fiber to forbid the scheduler from propagating cancelation to the fiber.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-block"><a href="#val-block" class="anchor"></a><code><span><span class="keyword">val</span> block : <span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>block ()</code> suspends the current fiber until it is canceled at which point the cancelation exception will be raised.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>in case propagation of cancelation has been <a href="#val-protect" title="protect">forbidden</a>.</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Sys_error</code> <p>in case the underlying computation of the fiber is forced to return during <code>block</code>. This is only possible when the fiber has been spawned through another library.</p></li></ul></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><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>terminate_after ~seconds thunk</code> arranges to terminate the execution of <code>thunk</code> on the current fiber after the specified timeout in <code>seconds</code>.</p><p>Using <code>terminate_after</code> one can attempt any blocking operation that supports cancelation with a timeout. For example, one could try to <a href="../../Picos_std_sync/Ivar/index.html#val-read" title="Picos_std_sync.Ivar.read"><code>read</code></a> an <a href="../../Picos_std_sync/Ivar/index.html" title="Picos_std_sync.Ivar"><code>Ivar</code></a> with a timeout</p><pre class="language-ocaml"><code> let peek_in ~seconds ivar =
|
||
match
|
||
Control.terminate_after ~seconds @@ fun () ->
|
||
Ivar.read ivar
|
||
with
|
||
| value -> Some value
|
||
| exception Control.Terminate -> None</code></pre><p>or one could try to <span class="xref-unresolved" title="Picos_io.Unix.connect"><code>connect</code></span> a socket with a timeout</p><pre class="language-ocaml"><code> let try_connect_in ~seconds socket sockaddr =
|
||
match
|
||
Control.terminate_after ~seconds @@ fun () ->
|
||
Unix.connect socket sockaddr
|
||
with
|
||
| () -> true
|
||
| exception Control.Terminate -> false</code></pre><p>using the <code>Picos_io.Unix</code> module.</p><p>The optional <code>callstack</code> argument specifies the number of callstack entries to capture with the <a href="#exception-Terminate" title="Control.Terminate"><code>Terminate</code></a> exception. The default is <code>0</code>.</p><p>As an example, <code>terminate_after</code> could be implemented using <a href="../Bundle/index.html"><code>Bundle</code></a> as follows:</p><pre class="language-ocaml"><code> let terminate_after ?callstack ~seconds thunk =
|
||
Bundle.join_after @@ fun bundle ->
|
||
Bundle.terminate_after ?callstack ~seconds bundle;
|
||
thunk ()</code></pre></div></div></div></body></html>
|