mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-15 07:16:09 -05:00
8 lines
11 KiB
HTML
8 lines
11 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Background_thread (moonpool.Moonpool.Background_thread)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.1"/><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">moonpool</a> » <a href="../index.html">Moonpool</a> » Background_thread</nav><header class="odoc-preamble"><h1>Module <code><span>Moonpool.Background_thread</span></code></h1><p>A simple runner with a single background thread.</p><p>Because this is guaranteed to have a single worker thread, tasks scheduled in this runner always run asynchronously but in a sequential fashion.</p><p>This is similar to <a href="../Fifo_pool/index.html"><code>Fifo_pool</code></a> with exactly one thread.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> NEXT_RELEASE</li></ul></header><div class="odoc-content"><div class="odoc-include"><details open="open"><summary class="spec include"><code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <a href="../Runner/index.html">Runner</a></span></code></summary><div class="odoc-spec"><div class="spec type anchored" id="type-task"><a href="#type-task" class="anchor"></a><code><span><span class="keyword">type</span> task</span><span> = <span>unit <span class="arrow">-></span></span> unit</span></code></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> t</span></code></div><div class="spec-doc"><p>A runner.</p><p>If a runner is no longer needed, <a href="#val-shutdown"><code>shutdown</code></a> can be used to signal all worker threads in it to stop (after they finish their work), and wait for them to stop.</p><p>The threads are distributed across a fixed domain pool (whose size is determined by <code>Domain.recommended_domain_count</code> on OCaml 5, and simple the single runtime on OCaml 4).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-size"><a href="#val-size" class="anchor"></a><code><span><span class="keyword">val</span> size : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Number of threads/workers.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-num_tasks"><a href="#val-num_tasks" class="anchor"></a><code><span><span class="keyword">val</span> num_tasks : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Current number of tasks. This is at best a snapshot, useful for metrics and debugging.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-shutdown"><a href="#val-shutdown" class="anchor"></a><code><span><span class="keyword">val</span> shutdown : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Shutdown the runner and wait for it to terminate. Idempotent.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-shutdown_without_waiting"><a href="#val-shutdown_without_waiting" class="anchor"></a><code><span><span class="keyword">val</span> shutdown_without_waiting : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Shutdown the pool, and do not wait for it to terminate. Idempotent.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Shutdown"><a href="#exception-Shutdown" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Shutdown</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-run_async"><a href="#val-run_async" class="anchor"></a><code><span><span class="keyword">val</span> run_async : <span><span class="optlabel">?ls</span>:<a href="../Task_local_storage/index.html#type-storage">Task_local_storage.storage</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-task">task</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>run_async pool f</code> schedules <code>f</code> for later execution on the runner in one of the threads. <code>f()</code> will run on one of the runner's worker threads/domains.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">ls</span> <p>if provided, run the task with this initial local storage</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Shutdown"><code>Shutdown</code></a> <p>if the runner was shut down before <code>run_async</code> was called.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-run_wait_block"><a href="#val-run_wait_block" class="anchor"></a><code><span><span class="keyword">val</span> run_wait_block : <span><span class="optlabel">?ls</span>:<a href="../Task_local_storage/index.html#type-storage">Task_local_storage.storage</a> <span class="arrow">-></span></span> <span><a href="#type-t">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 class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>run_wait_block pool f</code> schedules <code>f</code> for later execution on the pool, like <a href="#val-run_async"><code>run_async</code></a>. It then blocks the current thread until <code>f()</code> is done executing, and returns its result. If <code>f()</code> raises an exception, then <code>run_wait_block pool f</code> will raise it as well.</p><p><b>NOTE</b> be careful with deadlocks (see notes in <a href="../Fut/index.html#val-wait_block"><code>Fut.wait_block</code></a> about the required discipline to avoid deadlocks).</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Shutdown"><code>Shutdown</code></a> <p>if the runner was already shut down</p></li></ul></div></div><h3 id="implementing-runners"><a href="#implementing-runners" class="anchor"></a>Implementing runners</h3><div class="odoc-spec"><div class="spec module anchored" id="module-For_runner_implementors"><a href="#module-For_runner_implementors" class="anchor"></a><code><span><span class="keyword">module</span> <a href="For_runner_implementors/index.html">For_runner_implementors</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>This module is specifically intended for users who implement their own runners. Regular users of Moonpool should not need to look at it.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_current_runner"><a href="#val-get_current_runner" class="anchor"></a><code><span><span class="keyword">val</span> get_current_runner : <span>unit <span class="arrow">-></span></span> <span><a href="#type-t">t</a> option</span></span></code></div><div class="spec-doc"><p>Access the current runner. This returns <code>Some r</code> if the call happens on a thread that belongs in a runner.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.5</li></ul></div></div></details></div><div class="odoc-spec"><div class="spec type anchored" id="type-create_args"><a href="#type-create_args" class="anchor"></a><code><span><span class="keyword">type</span> <span>('a, 'b) create_args</span></span><span> =
|
||
<span><span class="optlabel">?on_init_thread</span>:<span>(<span><span class="label">dom_id</span>:int <span class="arrow">-></span></span> <span><span class="label">t_id</span>:int <span class="arrow">-></span></span> <span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?on_exit_thread</span>:<span>(<span><span class="label">dom_id</span>:int <span class="arrow">-></span></span> <span><span class="label">t_id</span>:int <span class="arrow">-></span></span> <span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?on_exn</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> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?around_task</span>:<span>(<span>(<span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> * <span>(<span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> unit)</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?name</span>:string <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Arguments used in <a href="#val-create"><code>create</code></a>. See <a href="#val-create"><code>create</code></a> for explanations.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create : <span><span>(<span>unit <span class="arrow">-></span></span> <a href="#type-t">t</a>, <span class="type-var">_</span>)</span> <a href="#type-create_args">create_args</a></span></span></code></div><div class="spec-doc"><p>Create the background runner</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_"><a href="#val-with_" class="anchor"></a><code><span><span class="keyword">val</span> with_ : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span>(<span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span>, <span class="type-var">_</span>)</span> <a href="#type-create_args">create_args</a></span></span></code></div></div></div></body></html>
|