mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-17 16:16:48 -05:00
8 lines
12 KiB
HTML
8 lines
12 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Fifo_pool (moonpool.Moonpool.Fifo_pool)</title><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.3.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> » Fifo_pool</nav><header class="odoc-preamble"><h1>Module <code><span>Moonpool.Fifo_pool</span></code></h1><p>A simple thread pool in FIFO order.</p><p>FIFO: first-in, first-out. Basically tasks are put into a queue, and worker threads pull them out of the queue at the other end.</p><p>Since this uses a single blocking queue to manage tasks, it's very simple and reliable. The number of worker threads is fixed, but they are spread over several domains to enable parallelism.</p><p>This can be useful for latency-sensitive applications (e.g. as a pool of workers for network servers). Work-stealing pools might have higher throughput but they're very unfair to some tasks; by contrast, here, older tasks have priority over younger tasks.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.5</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><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="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><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></div></div><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">?num_threads</span>:int <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><code>create ()</code> makes a new thread pool.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">on_init_thread</span> <p>called at the beginning of each new thread in the pool.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">min</span> <p>minimum size of the pool. See <a href="#type-create_args"><code>Pool.create_args</code></a>. The default is <code>Domain.recommended_domain_count()</code>, ie one worker per CPU core. On OCaml 4 the default is <code>4</code> (since there is only one domain).</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">on_exit_thread</span> <p>called at the end of each worker thread in the pool.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">around_task</span> <p>a pair of <code>before, after</code> functions ran around each task. See <a href="#type-create_args"><code>Pool.create_args</code></a>.</p></li></ul></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 class="spec-doc"><p><code>with_ () f</code> calls <code>f pool</code>, where <code>pool</code> is obtained via <a href="#val-create"><code>create</code></a>. When <code>f pool</code> returns or fails, <code>pool</code> is shutdown and its resources are released. Most parameters are the same as in <a href="#val-create"><code>create</code></a>.</p></div></div></div></body></html>
|