mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-20 09:36:43 -05:00
2 lines
8.2 KiB
HTML
2 lines
8.2 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Runner (moonpool.Moonpool.Runner)</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> » Runner</nav><header class="odoc-preamble"><h1>Module <code><span>Moonpool.Runner</span></code></h1><p>Interface for runners.</p><p>This provides an abstraction for running tasks in the background, which is implemented by various thread pools.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.3</li></ul></header><nav class="odoc-toc"><ul><li><a href="#implementing-runners">Implementing runners</a></li></ul></nav><div class="odoc-content"><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-t">Task_local_storage.t</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-t">Task_local_storage.t</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><div class="odoc-spec"><div class="spec value anchored" id="val-dummy"><a href="#val-dummy" class="anchor"></a><code><span><span class="keyword">val</span> dummy : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Runner that fails when scheduling tasks on it. Calling <a href="#val-run_async"><code>run_async</code></a> on it will raise Failure.</p></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><div class="odoc-spec"><div class="spec value anchored" id="val-get_current_storage"><a href="#val-get_current_storage" class="anchor"></a><code><span><span class="keyword">val</span> get_current_storage : <span>unit <span class="arrow">-></span></span> <span><a href="../Task_local_storage/index.html#type-t">Task_local_storage.t</a> option</span></span></code></div><div class="spec-doc"><p><code>get_current_storage runner</code> gets the local storage for the currently running task.</p></div></div></div></body></html>
|