mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-06 03:05:30 -05:00
4 lines
11 KiB
HTML
4 lines
11 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Lwt_main (lwt.Lwt_main)</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> » <a href="../index.html">lwt</a> » Lwt_main</nav><header class="odoc-preamble"><h1>Module <code><span>Lwt_main</span></code></h1><p>Main loop and event queue</p></header><div class="odoc-content"><p>This module controls the ``main-loop'' of Lwt.</p><div class="odoc-spec"><div class="spec value anchored" id="val-run"><a href="#val-run" class="anchor"></a><code><span><span class="keyword">val</span> run : <span><span><span class="type-var">'a</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>Lwt_main.run p</code> calls the Lwt scheduler, performing I/O until <code>p</code> resolves. <code>Lwt_main.run p</code> returns the value in <code>p</code> if <code>p</code> is fulfilled. If <code>p</code> is rejected with an exception instead, <code>Lwt_main.run p</code> raises that exception.</p><p>Every native and bytecode program that uses Lwt should call this function at its top level. It implements the Lwt main loop.</p><p>Example:</p><pre class="language-ocaml"><code>let main () = Lwt_io.write_line Lwt_io.stdout "hello world"
|
||
|
||
let () = Lwt_main.run (main ())</code></pre><p><code>Lwt_main.run</code> is not available when targeting JavaScript, because the environment (such as Node.js or the browser's script engine) implements the I/O loop.</p><p>On Unix, calling <code>Lwt_main.run</code> installs a <code>SIGCHLD</code> handler, which is needed for the implementations of <a href="../Lwt_unix/index.html#val-waitpid"><code>Lwt_unix.waitpid</code></a> and <a href="../Lwt_unix/index.html#val-wait4"><code>Lwt_unix.wait4</code></a>. As a result, programs that call <code>Lwt_main.run</code> and also use non-Lwt system calls need to handle those system calls failing with <code>EINTR</code>.</p><p>Nested calls to <code>Lwt_main.run</code> are not allowed. That is, do not call <code>Lwt_main.run</code> in a callback triggered by a promise that is resolved by an outer invocation of <code>Lwt_main.run</code>. If your program makes such a call, <code>Lwt_main.run</code> will raise <code>Failure</code>. This should be considered a logic error (i.e., code making such a call is inherently broken).</p><p>In addition, note that if you have set the exception filter to let runtime exceptions bubble up (via <code>Lwt.Exception_filter.(set handle_all_except_runtime)</code>) then Lwt does not attempt to catch exceptions thrown by the OCaml runtime. Specifically, in this case, Lwt lets <code>Out_of_memory</code> and <code>Stack_overflow</code> exceptions traverse all of its functions and bubble up to the caller of <code>Lwt_main.run</code>. Moreover because these exceptions are left to traverse the call stack, they leave the internal data-structures in an inconsistent state. For this reason, calling <code>Lwt_main.run</code> again after such an exception will raise <code>Failure</code>.</p><p>It is not safe to call <code>Lwt_main.run</code> in a function registered with <code>Stdlib.at_exit</code>, use <a href="#val-at_exit"><code>Lwt_main.at_exit</code></a> instead.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-yield"><a href="#val-yield" class="anchor"></a><code><span><span class="keyword">val</span> yield : <span>unit <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>yield ()</code> is a pending promise that is fulfilled after Lwt finishes calling all currently ready callbacks, i.e. it is fulfilled on the next “tick.”</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Since 5.5.0 <code>yield</code> is deprecated in favor of the more general <a href="../Lwt/index.html#val-pause"><code>Lwt.pause</code></a> in order to avoid discrepancies in resolution (see below) and stay compatible with other execution environments such as js_of_ocaml.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-abandon_yielded_and_paused"><a href="#val-abandon_yielded_and_paused" class="anchor"></a><code><span><span class="keyword">val</span> abandon_yielded_and_paused : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Causes promises created with <a href="../Lwt/index.html#val-pause"><code>Lwt.pause</code></a> and <a href="#val-yield"><code>Lwt_main.yield</code></a> to remain forever pending.</p><p>(Note that <code>yield</code> is deprecated in favor of the more general <a href="../Lwt/index.html#val-pause"><code>Lwt.pause</code></a>.)</p><p>This is meant for use with <a href="../Lwt_unix/index.html#val-fork"><code>Lwt_unix.fork</code></a>, as a way to “abandon” more promise chains that are pending in your process.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Since 5.7 <code>abandon_yielded_and_paused</code> is deprecated in favour of <code>Lwt.abandon_paused</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec module-type anchored" id="module-type-Hooks"><a href="#module-type-Hooks" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> <a href="module-type-Hooks/index.html">Hooks</a></span><span> = <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Hook sequences. Each module of this type is a set of hooks, to be run by Lwt at certain points during execution. See modules <a href="Enter_iter_hooks/index.html"><code>Enter_iter_hooks</code></a>, <a href="Leave_iter_hooks/index.html"><code>Leave_iter_hooks</code></a>, and <a href="Exit_hooks/index.html"><code>Exit_hooks</code></a>.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Enter_iter_hooks"><a href="#module-Enter_iter_hooks" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Enter_iter_hooks/index.html">Enter_iter_hooks</a></span><span> : <a href="module-type-Hooks/index.html">Hooks</a> <span class="keyword">with</span> <span><span class="keyword">type</span> <span>'return_value <a href="module-type-Hooks/index.html#type-kind">kind</a></span> = <span class="type-var">'return_value</span></span></span></code></div><div class="spec-doc"><p>Hooks, of type <code>unit -> unit</code>, that are called before each iteration of the Lwt main loop.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Leave_iter_hooks"><a href="#module-Leave_iter_hooks" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Leave_iter_hooks/index.html">Leave_iter_hooks</a></span><span> : <a href="module-type-Hooks/index.html">Hooks</a> <span class="keyword">with</span> <span><span class="keyword">type</span> <span>'return_value <a href="module-type-Hooks/index.html#type-kind">kind</a></span> = <span class="type-var">'return_value</span></span></span></code></div><div class="spec-doc"><p>Hooks, of type <code>unit -> unit</code>, that are called after each iteration of the Lwt main loop.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Exit_hooks"><a href="#module-Exit_hooks" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Exit_hooks/index.html">Exit_hooks</a></span><span> : <a href="module-type-Hooks/index.html">Hooks</a> <span class="keyword">with</span> <span><span class="keyword">type</span> <span>'return_value <a href="module-type-Hooks/index.html#type-kind">kind</a></span> = <span><span class="type-var">'return_value</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></span></code></div><div class="spec-doc"><p>Promise-returning hooks, of type <code>unit -> unit Lwt.t</code>, that are called at process exit. Exceptions raised by these hooks are ignored.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-enter_iter_hooks"><a href="#val-enter_iter_hooks" class="anchor"></a><code><span><span class="keyword">val</span> enter_iter_hooks : <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <a href="../Lwt_sequence/index.html#type-t">Lwt_sequence.t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Use module <a href="Enter_iter_hooks/index.html"><code>Enter_iter_hooks</code></a>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-leave_iter_hooks"><a href="#val-leave_iter_hooks" class="anchor"></a><code><span><span class="keyword">val</span> leave_iter_hooks : <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <a href="../Lwt_sequence/index.html#type-t">Lwt_sequence.t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Use module <a href="Leave_iter_hooks/index.html"><code>Leave_iter_hooks</code></a>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_hooks"><a href="#val-exit_hooks" class="anchor"></a><code><span><span class="keyword">val</span> exit_hooks : <span><span>(<span>unit <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <a href="../Lwt_sequence/index.html#type-t">Lwt_sequence.t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Use module <a href="Exit_hooks/index.html"><code>Exit_hooks</code></a>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-at_exit"><a href="#val-at_exit" class="anchor"></a><code><span><span class="keyword">val</span> at_exit : <span><span>(<span>unit <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt_main.at_exit hook</code> is the same as <code>ignore (Lwt_main.Exit_hooks.add_first hook)</code>.</p></div></div></div></body></html>
|