simon/moonpool
1
0
Fork 0
mirror of https://github.com/c-cube/moonpool.git synced 2025-12-06 03:05:30 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
moonpool/picos_std/Picos_std_awaitable/Awaitable/index.html
c-cube 1830dc8781 deploy: d79200f555
2025-09-26 19:08:06 +00:00

2 lines
10 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Awaitable (picos_std.Picos_std_awaitable.Awaitable)</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> &#x00BB; <a href="../../index.html">picos_std</a> &#x00BB; <a href="../index.html">Picos_std_awaitable</a> &#x00BB; Awaitable</nav><header class="odoc-preamble"><h1>Module <code><span>Picos_std_awaitable.Awaitable</span></code></h1><p>An awaitable atomic location.</p><p>This module provides a superset of the Stdlib <code>Atomic</code> API with more or less identical performance. The main difference is that a non-padded awaitable location takes an extra word of memory. Additionally a <a href="https://en.wikipedia.org/wiki/Futex">futex</a>-like API provides the ability to <a href="#val-await"><code>await</code></a> until an awaitable location is explicitly <a href="#val-signal"><code>signal</code></a>ed to potentially have a different value.</p><p>Awaitable locations can be used to implement many kinds of synchronization and communication primitives.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#atomic-api">Atomic API</a></li><li><a href="#futex-api">Futex API</a></li></ul></nav></div><div class="odoc-content"><h2 id="atomic-api"><a href="#atomic-api" class="anchor"></a>Atomic API</h2><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>Represents an awaitable atomic location.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-make"><a href="#val-make" class="anchor"></a><code><span><span class="keyword">val</span> make : <span><span class="optlabel">?padded</span>:bool <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</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>make initial</code> creates a new awaitable atomic location with the given <code>initial</code> value.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-make_contended"><a href="#val-make_contended" class="anchor"></a><code><span><span class="keyword">val</span> make_contended : <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</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>make_contended initial</code> is equivalent to <a href="#val-make" title="make"><code>make ~padded:true initial</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get"><a href="#val-get" class="anchor"></a><code><span><span class="keyword">val</span> get : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>get awaitable</code> is essentially equivalent to <code>Atomic.get awaitable</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-compare_and_set"><a href="#val-compare_and_set" class="anchor"></a><code><span><span class="keyword">val</span> compare_and_set : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> bool</span></code></div><div class="spec-doc"><p><code>compare_and_set awaitable before after</code> is essentially equivalent to <code>Atomic.compare_and_set awaitable before after</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exchange"><a href="#val-exchange" class="anchor"></a><code><span><span class="keyword">val</span> exchange : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>exchange awaitable after</code> is essentially equivalent to <code>Atomic.exchange awaitable after</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set"><a href="#val-set" class="anchor"></a><code><span><span class="keyword">val</span> set : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>set awaitable value</code> is equivalent to <a href="#val-exchange" title="exchange"><code>exchange awaitable value |&gt; ignore</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fetch_and_add"><a href="#val-fetch_and_add" class="anchor"></a><code><span><span class="keyword">val</span> fetch_and_add : <span><span>int <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span>int <span class="arrow">&#45;&gt;</span></span> int</span></code></div><div class="spec-doc"><p><code>fetch_and_add awaitable delta</code> is essentially equivalent to <code>Atomic.fetch_and_add awaitable delta</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-incr"><a href="#val-incr" class="anchor"></a><code><span><span class="keyword">val</span> incr : <span><span>int <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>incr awaitable</code> is equivalent to <a href="#val-fetch_and_add" title="fetch_and_add"><code>fetch_and_add awaitable (+1) |&gt; ignore</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-decr"><a href="#val-decr" class="anchor"></a><code><span><span class="keyword">val</span> decr : <span><span>int <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>incr awaitable</code> is equivalent to <a href="#val-fetch_and_add" title="fetch_and_add"><code>fetch_and_add awaitable (-1) |&gt; ignore</code></a>.</p></div></div><h2 id="futex-api"><a href="#futex-api" class="anchor"></a>Futex API</h2><div class="odoc-spec"><div class="spec value anchored" id="val-signal"><a href="#val-signal" class="anchor"></a><code><span><span class="keyword">val</span> signal : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>signal awaitable</code> tries to wake up one fiber <a href="#val-await"><code>await</code></a>in on the awaitable location.</p><p>🐌 Generally speaking one should avoid calling <code>signal</code> too frequently, because the queue of awaiters is stored separately from the awaitable location and it takes a bit of effort to locate it. For example, calling <code>signal</code> every time a value is added to an empty data structure might not be optimal. In many cases it is faster to explicitly mark the potential presence of awaiters in the data structure and avoid calling <code>signal</code> when it is definitely known that there are no awaiters.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-broadcast"><a href="#val-broadcast" class="anchor"></a><code><span><span class="keyword">val</span> broadcast : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>broadcast awaitable</code> tries to wake up all fibers <a href="#val-await"><code>await</code></a>ing on the awaitable location.</p><p>🐌 The same advice as with <a href="#val-signal"><code>signal</code></a> applies to <code>broadcast</code>. In addition, it is typically a good idea to avoid potentially waking up large numbers of fibers as it can easily lead to the <a href="https://en.wikipedia.org/wiki/Thundering_herd_problem">thundering herd</a> phenomana.</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">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>await awaitable before</code> suspends the current fiber until the awaitable is explicitly <a href="#val-signal"><code>signal</code></a>ed and has a value other than <code>before</code>.</p><p>⚠️ This operation is subject to the <a href="https://en.wikipedia.org/wiki/ABA_problem">ABA</a> problem. An <code>await</code> for value other than <code>A</code> may not return after the awaitable is signaled while having the value <code>B</code>, because at a later point the awaitable has again the value <code>A</code>. Furthermore, by the time an <code>await</code> for value other than <code>A</code> returns, the awaitable might already again have the value <code>A</code>.</p><p>⚠️ Atomic operations that change the value of an awaitable do not implicitly wake up awaiters.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Awaiter"><a href="#module-Awaiter" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Awaiter/index.html">Awaiter</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Low level interface for more flexible waiting.</p></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink