simon/moonpool
1
0
Fork 0
mirror of https://github.com/c-cube/moonpool.git synced 2025-12-10 21:24:05 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
moonpool/picos_std/Picos_std_event/Event/index.html
c-cube c519fa45b8 deploy: 9b3c75124e
2024-09-04 16:10:21 +00:00

2 lines
11 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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>Event (picos_std.Picos_std_event.Event)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.2"/><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">picos_std</a> &#x00BB; <a href="../index.html">Picos_std_event</a> &#x00BB; Event</nav><header class="odoc-preamble"><h1>Module <code><span>Picos_std_event.Event</span></code></h1><p>First-class synchronous communication abstraction.</p><p>Events describe a thing that might happen in the future, or a concurrent offer or request that might be accepted or succeed, but is cancelable if some other event happens first.</p><p>See the <code>Picos_io_select</code> library for an example.</p><p>ℹ️ This module intentionally mimics the <a href="https://ocaml.org/manual/5.2/api/Event.html"><code>Event</code></a> module provided by the OCaml POSIX threads library.</p></header><nav class="odoc-toc"><ul><li><a href="#composing-events">Composing events</a></li><li><a href="#consuming-events">Consuming events</a></li><li><a href="#primitive-events">Primitive events</a></li></ul></nav><div class="odoc-content"><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>An event returning a value of type <code>'a</code>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-event"><a href="#type-event" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a event</span></span><span> = <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>An alias for the <a href="#type-t"><code>Event.t</code></a> type to match the <a href="https://ocaml.org/manual/5.2/api/Event.html"><code>Event</code></a> module signature.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-always"><a href="#val-always" class="anchor"></a><code><span><span class="keyword">val</span> always : <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>always value</code> returns an event that can always be committed to resulting in the given <code>value</code>.</p></div></div><h3 id="composing-events"><a href="#composing-events" class="anchor"></a>Composing events</h3><div class="odoc-spec"><div class="spec value anchored" id="val-choose"><a href="#val-choose" class="anchor"></a><code><span><span class="keyword">val</span> choose : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</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>choose events</code> return an event that offers all of the given events and then commits to at most one of them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap"><a href="#val-wrap" class="anchor"></a><code><span><span class="keyword">val</span> wrap : <span><span><span class="type-var">'b</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(<span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'a</span>)</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>wrap event fn</code> returns an event that acts as the given <code>event</code> and then applies the given function to the value in case the event is committed to.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map"><a href="#val-map" class="anchor"></a><code><span><span class="keyword">val</span> map : <span><span>(<span><span class="type-var">'b</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'a</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'b</span> <a href="#type-t">t</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>map fn event</code> is equivalent to <a href="#val-wrap" title="wrap"><code>wrap event fn</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-guard"><a href="#val-guard" class="anchor"></a><code><span><span class="keyword">val</span> guard : <span><span>(<span>unit <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>)</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>guard thunk</code> returns an event that, when <a href="#val-sync" title="sync">synchronized</a>, calls the <code>thunk</code>, and then behaves like the resulting event.</p><p>⚠️ Raising an exception from a <code>guard thunk</code> will result in raising that exception out of the <a href="#val-sync"><code>sync</code></a>. This may result in dropping the result of an event that committed just after the exception was raised. This means that you should treat an unexpected exception raised from <a href="#val-sync"><code>sync</code></a> as a fatal error.</p></div></div><h3 id="consuming-events"><a href="#consuming-events" class="anchor"></a>Consuming events</h3><div class="odoc-spec"><div class="spec value anchored" id="val-sync"><a href="#val-sync" class="anchor"></a><code><span><span class="keyword">val</span> sync : <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>sync event</code> synchronizes on the given event.</p><p>Synchronizing on an event executes in three phases:</p><ol><li>In the first phase offers or requests are made to communicate.</li><li>One of the offers or requests is committed to and all the other offers and requests are canceled.</li><li>A final result is computed from the value produced by the event.</li></ol><p>⚠️ <code>sync event</code> does not wait for the canceled concurrent requests to terminate. This means that you should arrange for guaranteed cleanup through other means such as the use of <a href="../../Picos_std_structured/index.html" title="Picos_std_structured">structured concurrency</a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-select"><a href="#val-select" class="anchor"></a><code><span><span class="keyword">val</span> select : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>select events</code> is equivalent to <a href="#val-sync" title="sync"><code>sync (choose events)</code></a>.</p></div></div><h3 id="primitive-events"><a href="#primitive-events" class="anchor"></a>Primitive events</h3><p>ℹ️ The <a href="../../../picos/Picos/Computation/index.html" title="Picos.Computation"><code>Computation</code></a> concept of <a href="../../../picos/Picos/index.html"><code>Picos</code></a> can be seen as a basic single-shot atomic event. This module builds on that concept to provide a composable API to concurrent services exposed through computations.</p><div class="odoc-spec"><div class="spec type anchored" id="type-request"><a href="#type-request" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a request</span></span><span> = </span><span>{</span></code><ol><li id="type-request.request" class="def record field anchored"><a href="#type-request.request" class="anchor"></a><code><span>request : 'r. <span><span><span>(<span>unit <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'r</span>)</span> <a href="../../../picos/Picos/Computation/index.html#type-t">Picos.Computation.t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'r</span>)</span> <span class="arrow">&#45;&gt;</span></span> unit;</span></code></li></ol><code><span>}</span></code></div><div class="spec-doc"><p>Represents a function that requests a concurrent service to update a <a href="../../../picos/Picos/Computation/index.html" title="Picos.Computation">computation</a>.</p><p>ℹ️ The computation passed to a request may be completed by some other event at any point. All primitive requests should be implemented carefully to take that into account. If the computation is completed by some other event, then the request should be considered as canceled, take no effect, and not leak any resources.</p><p>⚠️ Raising an exception from a <code>request</code> function will result in raising that exception out of the <a href="#val-sync"><code>sync</code></a>. This may result in dropping the result of an event that committed just after the exception was raised. This means that you should treat an unexpected exception raised from <a href="#val-sync"><code>sync</code></a> as a fatal error. In addition, you should arrange for concurrent services to report unexpected errors independently of the computation being passed to the service.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-from_request"><a href="#val-from_request" class="anchor"></a><code><span><span class="keyword">val</span> from_request : <span><span><span class="type-var">'a</span> <a href="#type-request">request</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>from_request { request }</code> creates an <a href="#" title="Event">event</a> from the request function.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-from_computation"><a href="#val-from_computation" class="anchor"></a><code><span><span class="keyword">val</span> from_computation : <span><span><span class="type-var">'a</span> <a href="../../../picos/Picos/Computation/index.html#type-t">Picos.Computation.t</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>from_computation source</code> creates an <a href="#" title="Event">event</a> that can be committed to once the given <code>source</code> computation has completed.</p><p>ℹ️ Committing to some other event does not cancel the <code>source</code> computation.</p></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink