mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-06 03:05:30 -05:00
356 lines
126 KiB
HTML
356 lines
126 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Lwt (lwt.Lwt)</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">lwt</a> » Lwt</nav><header class="odoc-preamble"><h1>Module <code><span>Lwt</span></code></h1><p>Asynchronous programming with promises.</p><p>A <b>promise</b> is a placeholder for a single value which might take a long time to compute. Speaking roughly, a promise is a <code>ref</code> that can be filled in later. To make that precise, here is how promises differ from <code>ref</code>s:</p><ul><li>A promise might not have a value yet. A promise in this state is called a <em>pending</em> promise.</li><li>Writing a value into a promise is called <em>resolving</em> it. A promise with a value is called a <em>resolved</em> promise.</li><li>Each promise can be resolved only once. After a promise has a value, the promise is immutable.</li><li>It's possible to attach <b>callbacks</b> to a promise. They will run when the promise has a value, i.e. is resolved. If the promise is already resolved when a callback is attached, the callback is run (almost) right away. If the promise is pending, the callback is put into a list and waits.</li></ul><p>So, promises are optional, write-once references, and when they don't yet have a value, they store a list of callbacks that are waiting for the value.</p><p>The waiting callbacks make promises a natural data type for asynchronous programming. For example, you can ask Lwt to <code>read</code> a file. Lwt immediately returns you only a <em>promise</em> for the data.</p><p>You can neglect this promise for a while. You can do some other computation, request more I/O, etc. At some point, you might decide to attach a callback to the <code>read</code> promise, maybe several callbacks.</p><p>In the meantime, the <code>read</code> operation is running in the background. Once it finishes, Lwt <em>resolves</em> the <code>read</code> promise by putting the data into it. Lwt then runs the callbacks you attached.</p><p>One of those might take the data, and ask Lwt to <code>write</code> it to STDOUT. Lwt gives you a promise for that, too, and the process repeats.</p><p>Lwt has a small amount of syntactic sugar to make this look as natural as possible:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let%lwt data = Lwt_io.(read_line stdin) in
|
||
let%lwt () = Lwt_io.printl data in
|
||
Lwt.return ()
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix echo.ml && ./a.out *)</code></pre><p>This is all explained in the next sections:</p><ul><li><a href="#3_Quickstart" title="3_Quickstart">Quick start</a> links these concepts to actual functions in Lwt – the most fundamental ones.</li><li><a href="#3_Tutorial" title="3_Tutorial">Tutorial</a> shows how to write examples like the above, and how concurrency happens.</li><li><a href="#3_Executionmodel" title="3_Executionmodel">Execution model</a> clarifies control flow when using Lwt.</li><li><a href="#3_GuidetotherestofLwt" title="3_GuidetotherestofLwt">Guide to the rest of Lwt</a> shows how <em>everything</em> else in Lwt fits into this framework.</li></ul><p>After that is the <a href="#2_Fundamentals" title="2_Fundamentals">reference proper</a>, which goes into <em>painful</em> levels of detail on every single type and value in this module, <code>Lwt</code>. Please be safe, and read only what you need from it :)</p><p>Happy asynchronous programming!</p></header><nav class="odoc-toc"><ul><li><a href="#3_Quickstart">Quick start</a></li><li><a href="#3_Tutorial">Tutorial</a></li><li><a href="#3_Executionmodel">Execution model</a></li><li><a href="#3_GuidetotherestofLwt">Guide to the rest of Lwt</a></li><li><a href="#2_Fundamentals">Fundamentals</a><ul><li><a href="#promises">Promises</a></li><li><a href="#resolving">Resolving</a></li><li><a href="#callbacks">Callbacks</a></li></ul></li><li><a href="#2_Rejection">Rejection</a></li><li><a href="#2_Concurrency">Concurrency</a><ul><li><a href="#multiple-wait">Multiple wait</a></li><li><a href="#racing">Racing</a></li></ul></li><li><a href="#2_Cancellation">Cancellation</a><ul><li><a href="#cancellation-tweaks">Cancellation tweaks</a></li></ul></li><li><a href="#2_Convenience">Convenience</a><ul><li><a href="#callback-helpers">Callback helpers</a></li><li><a href="#infix-operators">Infix operators</a></li><li><a href="#pre-allocated-promises">Pre-allocated promises</a></li><li><a href="#trivial-promises">Trivial promises</a></li><li><a href="#result-type">Result type</a></li><li><a href="#state-query">State query</a></li></ul></li><li><a href="#2_Deprecated">Deprecated</a><ul><li><a href="#implicit-callback-arguments">Implicit callback arguments</a></li><li><a href="#immediate-resolving">Immediate resolving</a></li><li><a href="#linked-lists-of-promises">Linked lists of promises</a></li><li><a href="#yielding">Yielding</a></li><li><a href="#function-lifters">Function lifters</a></li><li><a href="#unscoped-infix-operators">Unscoped infix operators</a></li><li><a href="#miscellaneous">Miscellaneous</a><ul><li><a href="#runtime-exception-filters">Runtime exception filters</a></li></ul></li></ul></li></ul></nav><div class="odoc-content"><h4 id="3_Quickstart"><a href="#3_Quickstart" class="anchor"></a>Quick start</h4><p><em>All</em> of Lwt is variations on:</p><ul><li><b>Promises</b> of type <code>'a </code><a href="#type-t"><code>Lwt.t</code></a> are placeholders for values of type <code>'a</code>.</li><li><a href="#val-bind"><code>Lwt.bind</code></a> attaches <b>callbacks</b> to promises. When a promise gets a value, its callbacks are called.</li><li>Separate <b>resolvers</b> of type <code>'a </code><a href="#type-u"><code>Lwt.u</code></a> are used to write values into promises, through <a href="#val-wakeup_later"><code>Lwt.wakeup_later</code></a>.</li><li>Promises and resolvers are created in pairs using <a href="#val-wait"><code>Lwt.wait</code></a>. Lwt I/O functions call <a href="#val-wait"><code>Lwt.wait</code></a> internally, but return only the promise.</li><li><a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> is used to wait on one “top-level” promise. When that promise gets a value, the program terminates.</li></ul><h4 id="3_Tutorial"><a href="#3_Tutorial" class="anchor"></a>Tutorial</h4><p>Let's read from STDIN. The first version is written using ordinary values from the OCaml standard library. This makes the program block until the user enters a line:</p><pre class="language-ocaml"><code>let () =
|
||
let line : string = read_line () in
|
||
print_endline "Now unblocked!";
|
||
ignore line
|
||
|
||
(* ocamlfind opt -linkpkg code.ml && ./a.out *)</code></pre><p>If we use a promise instead, execution continues immediately:</p><pre class="language-ocaml"><code>let () =
|
||
let line_promise : string Lwt.t =
|
||
Lwt_io.(read_line stdin) in
|
||
print_endline "Execution just continues...";
|
||
ignore line_promise
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>Indeed, this program is a little <em>too</em> asynchronous – it exits right away! Let's force it to wait for <code>line_promise</code> at the end by calling <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>:</p><pre class="language-ocaml"><code>let () =
|
||
let line_promise : string Lwt.t =
|
||
Lwt_io.(read_line stdin) in
|
||
print_endline "Execution just continues...";
|
||
|
||
let line : string =
|
||
Lwt_main.run line_promise in
|
||
ignore line
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p><a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> should only be called once, on one promise, at the top level of your program. Most of the time, waiting for promises is done using <code>let%lwt</code>. That is the recommended syntactic sugar for <a href="#val-bind"><code>Lwt.bind</code></a>, and is pronounced “bind”:</p><pre class="language-ocaml"><code>let () =
|
||
let p : unit Lwt.t =
|
||
let%lwt line_1 = Lwt_io.(read_line stdin) in
|
||
let%lwt line_2 = Lwt_io.(read_line stdin) in
|
||
Lwt_io.printf "%s and %s\n" line_1 line_2
|
||
in
|
||
|
||
Lwt_main.run p
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>The way that works is everything in scope after the “<code>in</code>” in “<code>let%lwt x =</code> ... <code>in</code> ...” goes into a callback, and “<code>x</code>” is that callback's argument. So, we could have been very explicit, and written the code like this:</p><pre class="language-ocaml"><code>let () =
|
||
let p : unit Lwt.t =
|
||
let line_1_promise : string Lwt.t = Lwt_io.(read_line stdin) in
|
||
Lwt.bind line_1_promise (fun (line_1 : string) ->
|
||
|
||
let line_2_promise : string Lwt.t = Lwt_io.(read_line stdin) in
|
||
Lwt.bind line_2_promise (fun (line_2 : string) ->
|
||
|
||
Lwt_io.printf "%s and %s\n" line_1 line_2))
|
||
in
|
||
|
||
Lwt_main.run p
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>But, as you can see, this is verbose, and the indentation gets a bit crazy. So, we will always use <code>let%lwt</code>.</p><p>The code above reads two lines in sequence, because we ask Lwt to wait for <code>line_1</code>, before calling the second <a href="../Lwt_io/index.html#val-read_line"><code>Lwt_io.read_line</code></a> in the callback, to start the second I/O.</p><p>We could also run I/O <em>concurrently</em>. All we have to do is not start the second I/O in a callback of the first. Because it doesn't make sense to read two lines from STDIN concurrently, let's start two waits instead:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let three_seconds : unit Lwt.t = Lwt_unix.sleep 3. in
|
||
let five_seconds : unit Lwt.t = Lwt_unix.sleep 5. in
|
||
let%lwt () = three_seconds in
|
||
let%lwt () = Lwt_io.printl "3 seconds passed" in
|
||
let%lwt () = five_seconds in
|
||
Lwt_io.printl "Only 2 more seconds passed"
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>This program takes about five seconds to run. We are still new to <code>let%lwt</code>, so let's desugar it:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let three_seconds : unit Lwt.t = Lwt_unix.sleep 3. in
|
||
let five_seconds : unit Lwt.t = Lwt_unix.sleep 5. in
|
||
|
||
(* Both waits have already been started at this point! *)
|
||
|
||
Lwt.bind three_seconds (fun () ->
|
||
(* This is 3 seconds later. *)
|
||
Lwt.bind (Lwt_io.printl "3 seconds passed") (fun () ->
|
||
Lwt.bind five_seconds (fun () ->
|
||
(* Only 2 seconds were left in the 5-second wait, so
|
||
this callback runs 2 seconds after the first callback. *)
|
||
Lwt_io.printl "Only 2 more seconds passed")))
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>And that's it! Concurrency in Lwt is simply a matter of whether you start an operation in the callback of another one or not. As a convenience, Lwt provides a few <a href="#2_Concurrency" title="2_Concurrency">helpers</a> for common concurrency patterns.</p><h4 id="3_Executionmodel"><a href="#3_Executionmodel" class="anchor"></a>Execution model</h4><p>It's important to understand that promises are a pure-OCaml data type. They don't do any fancy scheduling or I/O. They are just lists of callbacks (if pending), or containers for one value (if resolved).</p><p>The interesting function is <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>. It's a wrapper around <a href="http://man7.org/linux/man-pages/man2/select.2.html"><code>select(2)</code></a>, <a href="http://man7.org/linux/man-pages/man7/epoll.7.html"><code>epoll(7)</code></a>, <a href="https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2"><code>kqueue(2)</code></a>, or whatever asynchronous I/O API your system provides. On browsers, the work of <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> is done by the surrounding JavaScript engine, so you don't call <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> from inside your program. But the execution model is still the same, and the description below applies!</p><p>To avoid writing out “underlying asynchronous I/O API,” we'll assume, in this section, that the API is <code>select(2)</code>. That's just for the sake of abbreviation. It doesn't actually matter, for most purposes, what the underlying I/O API is.</p><p>Let's use the program from the tutorial that reads two lines as an example. Here it is, again, in its desugared form:</p><pre class="language-ocaml"><code>let () =
|
||
let p : unit Lwt.t =
|
||
let line_1_promise : string Lwt.t = Lwt_io.(read_line stdin) in
|
||
Lwt.bind line_1_promise (fun (line_1 : string) ->
|
||
|
||
let line_2_promise : string Lwt.t = Lwt_io.(read_line stdin) in
|
||
Lwt.bind line_2_promise (fun (line_2 : string) ->
|
||
|
||
Lwt_io.printf "%s and %s\n" line_1 line_2))
|
||
in
|
||
|
||
Lwt_main.run p
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p><a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> is your program's main I/O loop. You pass it a single promise, and it:</p><ol><li>Uses <code>select(2)</code> to put your process to sleep until the next I/O completes.</li><li>That next I/O happens to be the one that reads <code>line_1</code>. <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> knows that I/O is supposed to resolve <code>line_1_promise</code>, so it puts <code>line_1</code> into the promise and resolves it.</li><li>Resolving is an ordinary OCaml operation. It causes all the callbacks of <code>line_1_promise</code> to run, one after another. Each callback is also ordinary OCaml code. In our case, there is only one callback, but in general, there might be several, and they might also resolve additional promises. So, promise resolution triggers a “cascade” of callbacks. Eventually, however, we should run out of callbacks, and control will return to <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>.</li><li>In our example, our one callback registers a second I/O with <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> – the one that will read <code>line_2</code>. There are no callbacks left to run after that, so control returns to <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>.</li><li><a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> goes back to sleep again by calling <code>select(2)</code>, now waiting for the second I/O that we just registered. The loop repeats itself from step 1.</li></ol><p>This has two major implications, one good and one bad. Let's start with the bad one.</p><p><b>(1)</b> If one of your callbacks enters an infinite loop, calls an Lwt-unfriendly blocking I/O, or just runs for a really long time, it won't return control to <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> anytime soon. That means <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> won't get a chance to resolve any other Lwt I/O promises, even if the underlying I/O operations complete.</p><p>In case your callback is just using the CPU for a really long time, you can insert a few calls to <a href="#val-pause"><code>Lwt.pause</code></a> into it, and resume your computation in callbacks of <code>pause</code>. This is basically the same as <a href="../Lwt_unix/index.html#val-sleep"><code>Lwt_unix.sleep</code></a><code> 0.</code> – it's a promise that will be resolved by <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> <em>after</em> any other I/O resolutions that are already in its queue.</p><p><b>(2)</b> The good implication is that all your callbacks run in a single thread. This means that in most situations, you don't have to worry about locks, synchronization, etc. Anything that is in the same callback is guaranteed to run without interruption. Lwt programs are often <em>much</em> easier to write and refactor, than equivalent programs written with threads – but both are concurrent!</p><h4 id="3_GuidetotherestofLwt"><a href="#3_GuidetotherestofLwt" class="anchor"></a>Guide to the rest of Lwt</h4><p>This module <code>Lwt</code> is the pure-OCaml definition of promises and callback-calling. It has a few extras on top of what's described above:</p><ul><li><a href="#2_Rejection" title="2_Rejection">Rejection</a>. Lwt promises can actually be resolved in two ways: <em>fulfilled</em> with a value, or <em>rejected</em> with an exception. There is nothing conceptually special about rejection – it's just that you can ask for callbacks to run only on fulfillment, only on rejection, etc.</li><li><a href="#2_Cancellation" title="2_Cancellation">Cancellation</a>. This is a special case of rejection, specifically with exception <a href="#exception-Canceled"><code>Lwt.Canceled</code></a>. It has extra helpers in the Lwt API.</li><li><a href="#2_Concurrency" title="2_Concurrency">Concurrency helpers</a>. All of these could be implemented on top of <a href="#val-bind"><code>Lwt.bind</code></a>. As we saw, Lwt concurrency requires only deciding whether to run something inside a callback, or outside it. These functions just implement common patterns, and make intent explicit.</li><li>Miscellaneous <a href="#2_Convenience" title="2_Convenience">helpers</a>, and <a href="#2_Deprecated" title="2_Deprecated">deprecated</a> APIs.</li></ul><p>The next layer above module <code>Lwt</code> is the pure-OCaml Lwt “core” library, which provides some promise-friendly patterns, like streams and mvars. This consists of the modules <a href="../Lwt_list/index.html"><code>Lwt_list</code></a>, <a href="../Lwt_stream/index.html"><code>Lwt_stream</code></a>, <a href="../Lwt_result/index.html"><code>Lwt_result</code></a>, <a href="../Lwt_mutex/index.html"><code>Lwt_mutex</code></a>, <a href="../Lwt_condition/index.html"><code>Lwt_condition</code></a>, <a href="../Lwt_mvar/index.html"><code>Lwt_mvar</code></a>, <a href="../Lwt_pool/index.html"><code>Lwt_pool</code></a>, and <a href="../Lwt_switch/index.html"><code>Lwt_switch</code></a>.</p><p>Above that is the Lwt Unix binding, where I/O begins. This includes the module <a href="../Lwt_main/index.html"><code>Lwt_main</code></a>, including the all-important <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>. The rest of the Unix binding consists of functions, each one of which...</p><ul><li>...starts a background I/O operation,</li><li>creates a promise for it and gives it to you,</li><li>registers with <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>, so if you attach callbacks to the promise, they will be called when the I/O operation completes.</li></ul><p>The functions are grouped into modules:</p><ul><li><a href="../Lwt_unix/index.html"><code>Lwt_unix</code></a> for Unix system calls.</li><li><a href="../Lwt_bytes/index.html"><code>Lwt_bytes</code></a> for Unix system calls on bigarrays.</li><li><a href="../Lwt_io/index.html"><code>Lwt_io</code></a> for <code>Stdlib</code>-like high-level channels, TCP servers, etc.</li><li><a href="../Lwt_process/index.html"><code>Lwt_process</code></a> for managing subprocesses.</li><li><a href="../Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a> for spawning system threads.</li><li>Miscellaneous modules <a href="../Lwt_gc/index.html"><code>Lwt_gc</code></a>, <a href="../Lwt_engine/index.html"><code>Lwt_engine</code></a>, <a href="../Lwt_throttle/index.html"><code>Lwt_throttle</code></a>, <a href="../Lwt_timeout/index.html"><code>Lwt_timeout</code></a>, <a href="../Lwt_sys/index.html"><code>Lwt_sys</code></a>.</li></ul><p>Warning! Introductory material ends and detailed reference begins!</p><h3 id="2_Fundamentals"><a href="#2_Fundamentals" class="anchor"></a>Fundamentals</h3><h4 id="promises"><a href="#promises" class="anchor"></a>Promises</h4><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>Promises for values of type <code>'a</code>.</p><p>A <b>promise</b> is a memory cell that is always in one of three <b>states</b>:</p><ul><li><em>fulfilled</em>, and containing one value of type <code>'a</code>,</li><li><em>rejected</em>, and containing one exception, or</li><li><em>pending</em>, in which case it may become fulfilled or rejected later.</li></ul><p>A <em>resolved</em> promise is one that is either fulfilled or rejected, i.e. not pending. Once a promise is resolved, its content cannot change. So, promises are <em>write-once references</em>. The only possible state changes are (1) from pending to fulfilled and (2) from pending to rejected.</p><p>Promises are typically “read” by attaching <b>callbacks</b> to them. The most basic functions for that are <a href="#val-bind"><code>Lwt.bind</code></a>, which attaches a callback that is called when a promise becomes fulfilled, and <a href="#val-catch"><code>Lwt.catch</code></a>, for rejection.</p><p>Promise variables of this type, <code>'a Lwt.t</code>, are actually <b>read-only</b> in Lwt. Separate <em>resolvers</em> of type <code>'a </code><a href="#type-u"><code>Lwt.u</code></a> are used to write to them. Promises and their resolvers are created together by calling <a href="#val-wait"><code>Lwt.wait</code></a>. There is one exception to this: most promises can be <em>canceled</em> by calling <a href="#val-cancel"><code>Lwt.cancel</code></a>, without going through a resolver.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-u"><a href="#type-u" class="anchor"></a><code><span><span class="keyword">type</span> <span>-'a u</span></span></code></div><div class="spec-doc"><p>Resolvers for promises of type <code>'a </code><a href="#type-t"><code>Lwt.t</code></a>.</p><p>Each resolver can be thought of as the <b>write end</b> of one promise. It can be passed to <a href="#val-wakeup_later"><code>Lwt.wakeup_later</code></a>, <a href="#val-wakeup_later_exn"><code>Lwt.wakeup_later_exn</code></a>, or <a href="#val-wakeup_later_result"><code>Lwt.wakeup_later_result</code></a> to resolve that promise.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wait"><a href="#val-wait" class="anchor"></a><code><span><span class="keyword">val</span> wait : <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span><span class="type-var">'a</span> <a href="#type-u">u</a></span></span></code></div><div class="spec-doc"><p>Creates a new pending <a href="#type-t" title="t">promise</a>, paired with its <a href="#type-u" title="u">resolver</a>.</p><p>It is rare to use this function directly. Many helpers in Lwt, and Lwt-aware libraries, call it internally, and return only the promise. You then chain the promises together using <a href="#val-bind"><code>Lwt.bind</code></a>.</p><p>However, it is important to understand <code>Lwt.wait</code> as the fundamental promise “constructor.” All other functions that evaluate to a promise can be, or are, eventually implemented in terms of it.</p></div></div><h4 id="resolving"><a href="#resolving" class="anchor"></a>Resolving</h4><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup_later"><a href="#val-wakeup_later" class="anchor"></a><code><span><span class="keyword">val</span> wakeup_later : <span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup_later r v</code> <em>fulfills</em>, with value <code>v</code>, the <em>pending</em> <a href="#type-t" title="t">promise</a> associated with <a href="#type-u" title="u">resolver</a> <code>r</code>. This triggers callbacks attached to the promise.</p><p>If the promise is not pending, <code>Lwt.wakeup_later</code> raises <a href="../../ocaml/Stdlib/index.html#exception-Invalid_argument"><code>Stdlib.Invalid_argument</code></a>, unless the promise is <a href="#val-cancel" title="Lwt.cancel">canceled</a>. If the promise is canceled, <code>Lwt.wakeup_later</code> has no effect.</p><p>If your program has multiple threads, it is important to make sure that <code>Lwt.wakeup_later</code> (and any similar function) is only called from the main thread. <code>Lwt.wakeup_later</code> can trigger callbacks attached to promises by the program, and these assume they are running in the main thread. If you need to communicate from a worker thread to the main thread running Lwt, see <a href="../Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a> or <a href="../Lwt_unix/index.html#val-send_notification"><code>Lwt_unix.send_notification</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup_later_exn"><a href="#val-wakeup_later_exn" class="anchor"></a><code><span><span class="keyword">val</span> wakeup_later_exn : <span><span><span class="type-var">_</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span>exn <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup_later_exn r exn</code> is like <a href="#val-wakeup_later"><code>Lwt.wakeup_later</code></a>, except, if the associated <a href="#type-t" title="t">promise</a> is <em>pending</em>, it is <em>rejected</em> with <code>exn</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return"><a href="#val-return" class="anchor"></a><code><span><span class="keyword">val</span> return : <span><span class="type-var">'a</span> <span class="arrow">-></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>Lwt.return v</code> creates a new <a href="#type-t" title="t">promise</a> that is <em>already fulfilled</em> with value <code>v</code>.</p><p>This is needed to satisfy the type system in some cases. For example, in a <code>match</code> expression where one case evaluates to a promise, the other cases have to evaluate to promises as well:</p><pre class="language-ocaml"><code>match need_input with
|
||
| true -> Lwt_io.(read_line stdin) (* Has type string Lwt.t... *)
|
||
| false -> Lwt.return "" (* ...so wrap empty string in a promise. *)</code></pre><p>Another typical usage is in <a href="#val-bind" title="Lwt.bind"><code>let%lwt</code></a>. The expression after the “<code>in</code>” has to evaluate to a promise. So, if you compute an ordinary value instead, you have to wrap it:</p><pre class="language-ocaml"><code>let%lwt line = Lwt_io.(read_line stdin) in
|
||
Lwt.return (line ^ ".")</code></pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fail"><a href="#val-fail" class="anchor"></a><code><span><span class="keyword">val</span> fail : <span>exn <span class="arrow">-></span></span> <span><span class="type-var">_</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.fail exn</code> is like <a href="#val-return"><code>Lwt.return</code></a>, except the new <a href="#type-t" title="t">promise</a> that is <em>already rejected</em> with <code>exn</code>.</p><p>Whenever possible, it is recommended to use <code>raise exn</code> instead, as <code>raise</code> captures a backtrace, while <code>Lwt.fail</code> does not. If you call <code>raise exn</code> in a callback that is expected by Lwt to return a promise, Lwt will automatically wrap <code>exn</code> in a rejected promise, but the backtrace will have been recorded by the OCaml runtime.</p><p>For example, <code>bind</code>'s second argument is a callback which returns a promise. And so it is recommended to use <code>raise</code> in the body of that callback. This applies to the aliases of <code>bind</code> as well: <code>( >>= )</code> and <code>( let* )</code>.</p><p>Use <code>Lwt.fail</code> only when you specifically want to create a rejected promise, to pass to another function, or store in a data structure.</p></div></div><h4 id="callbacks"><a href="#callbacks" class="anchor"></a>Callbacks</h4><div class="odoc-spec"><div class="spec value anchored" id="val-bind"><a href="#val-bind" class="anchor"></a><code><span><span class="keyword">val</span> bind : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.bind p_1 f</code> makes it so that <code>f</code> will run when <code>p_1</code> is <a href="#type-t" title="t"><em>fulfilled</em></a>.</p><p>When <code>p_1</code> is fulfilled with value <code>v_1</code>, the callback <code>f</code> is called with that same value <code>v_1</code>. Eventually, after perhaps starting some I/O or other computation, <code>f</code> returns promise <code>p_2</code>.</p><p><code>Lwt.bind</code> itself returns immediately. It only attaches the callback <code>f</code> to <code>p_1</code> – it does not wait for <code>p_2</code>. <em>What</em> <code>Lwt.bind</code> returns is yet a third promise, <code>p_3</code>. Roughly speaking, fulfillment of <code>p_3</code> represents both <code>p_1</code> and <code>p_2</code> becoming fulfilled, one after the other.</p><p>A minimal example of this is an echo program:</p><pre class="language-ocaml"><code>let () =
|
||
let p_3 =
|
||
Lwt.bind
|
||
Lwt_io.(read_line stdin)
|
||
(fun line -> Lwt_io.printl line)
|
||
in
|
||
Lwt_main.run p_3
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>Rejection of <code>p_1</code> and <code>p_2</code>, and raising an exception in <code>f</code>, are all forwarded to rejection of <code>p_3</code>.</p><p><b>Precise behavior</b></p><p><code>Lwt.bind</code> returns a promise <code>p_3</code> immediately. <code>p_3</code> starts out pending, and is resolved as follows:</p><ul><li>The first condition to wait for is that <code>p_1</code> becomes resolved. It does not matter whether <code>p_1</code> is already resolved when <code>Lwt.bind</code> is called, or becomes resolved later – the rest of the behavior is the same.</li><li>If and when <code>p_1</code> becomes resolved, it will, by definition, be either fulfilled or rejected.</li><li>If <code>p_1</code> is rejected, <code>p_3</code> is rejected with the same exception.</li><li>If <code>p_1</code> is fulfilled, with value <code>v</code>, <code>f</code> is applied to <code>v</code>.</li><li><code>f</code> may finish by returning the promise <code>p_2</code>, or raising an exception.</li><li>If <code>f</code> raises an exception, <code>p_3</code> is rejected with that exception.</li><li>Finally, the remaining case is when <code>f</code> returns <code>p_2</code>. From that point on, <code>p_3</code> is effectively made into a reference to <code>p_2</code>. This means they have the same state, undergo the same state changes, and performing any operation on one is equivalent to performing it on the other.</li></ul><p><b>Syntactic sugar</b></p><p><code>Lwt.bind</code> is almost never written directly, because sequences of <code>Lwt.bind</code> result in growing indentation and many parentheses:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
Lwt.bind Lwt_io.(read_line stdin) (fun line ->
|
||
Lwt.bind (Lwt_unix.sleep 1.) (fun () ->
|
||
Lwt_io.printf "One second ago, you entered %s\n" line))
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>The recommended way to write <code>Lwt.bind</code> is using the <code>let%lwt</code> syntactic sugar:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let%lwt line = Lwt_io.(read_line stdin) in
|
||
let%lwt () = Lwt_unix.sleep 1. in
|
||
Lwt_io.printf "One second ago, you entered %s\n" line
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>This uses the Lwt <a href="Ppx_lwt.html">PPX</a> (preprocessor). Note that we had to add package <code>lwt_ppx</code> to the command line for building this program. We will do that throughout this manual.</p><p>Another way to write <code>Lwt.bind</code>, that you may encounter while reading code, is with the <code>>>=</code> operator:</p><pre class="language-ocaml"><code>open Lwt.Infix
|
||
|
||
let () =
|
||
Lwt_main.run begin
|
||
Lwt_io.(read_line stdin) >>= fun line ->
|
||
Lwt_unix.sleep 1. >>= fun () ->
|
||
Lwt_io.printf "One second ago, you entered %s\n" line
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>The <code>>>=</code> operator comes from the module <a href="Infix/index.html"><code>Lwt.Infix</code></a>, which is why we opened it at the beginning of the program.</p><p>See also <a href="#val-map"><code>Lwt.map</code></a>.</p></div></div><h3 id="2_Rejection"><a href="#2_Rejection" class="anchor"></a>Rejection</h3><div class="odoc-spec"><div class="spec value external anchored" id="val-reraise"><a href="#val-reraise" class="anchor"></a><code><span><span class="keyword">val</span> reraise : <span>exn <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>reraise e</code> raises the exception <code>e</code>. Unlike <code>raise e</code>, <code>reraise e</code> preserves the existing exception backtrace and even adds a "Re-raised at" entry with the call location.</p><p>This function is intended to be used in the exception handlers of <code>Lwt.catch</code> and <code>Lwt.try_bind</code>.</p><p>It is also used in the code produced by Lwt_ppx.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-catch"><a href="#val-catch" class="anchor"></a><code><span><span class="keyword">val</span> catch : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span>(<span>exn <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></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>Lwt.catch f h</code> applies <code>f ()</code>, which returns a promise, and then makes it so that <code>h</code> (“handler”) will run when that promise is <a href="#type-t" title="t"><em>rejected</em></a>.</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
Lwt.catch
|
||
(fun () -> raise Exit)
|
||
(function
|
||
| Exit -> Lwt_io.printl "Got Stdlib.Exit"
|
||
| exn -> Lwt.reraise exn)
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>Despite the above code, the recommended way to write <code>Lwt.catch</code> is using the <code>try%lwt</code> syntactic sugar from the <a href="Ppx_lwt.html">PPX</a>. Here is an equivalent example:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
try%lwt raise Exit
|
||
with Exit -> Lwt_io.printl "Got Stdlb.Exit"
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>A particular advantage of the PPX syntax is that it is not necessary to artificially insert a catch-all <code>exn -> reraise exn</code> case. Like in the core language's <code>try</code> expression, the catch-all case is implied in <code>try%lwt</code>.</p><p><code>Lwt.catch</code> is a counterpart to <a href="#val-bind"><code>Lwt.bind</code></a> – <a href="#val-bind"><code>Lwt.bind</code></a> is for fulfillment, and <a href="#val-catch"><code>Lwt.catch</code></a> is for rejection.</p><p>As with <a href="#val-bind"><code>Lwt.bind</code></a>, three promises are involved:</p><ul><li><code>p_1</code>, the promise returned from applying <code>f ()</code>.</li><li><code>p_2</code>, the promise returned from applying <code>h exn</code>.</li><li><code>p_3</code>, the promise returned by <code>Lwt.catch</code> itself.</li></ul><p>The remainder is (1) a precise description of how <code>p_3</code> is resolved, and (2) a warning about accidentally using ordinary <code>try</code> for exception handling in asynchronous code.</p><p><b>(1)</b> <code>Lwt.catch</code> first applies <code>f ()</code>. It then returns <code>p_3</code> immediately. <code>p_3</code> starts out pending. It is resolved as follows:</p><ul><li>If <code>f ()</code> returned a promise <code>p_1</code>, and <code>p_1</code> becomes fulfilled, <code>p_3</code> is fulfilled with the same value.</li><li><code>p_1</code> can instead become rejected. There is one other possibility: <code>f ()</code> itself raised an exception, instead of returning a promise. The behavior of <code>Lwt.catch</code> is the same whether <code>f ()</code> raised an exception, or returned a promise that is later rejected with an exception. Let's call the exception <code>exn</code>.</li><li><code>h exn</code> is applied.</li><li><code>h exn</code> may return a promise, or might itself raise an exception. The first case is the interesting one, but the exception case is simple, so we cover the exception case first.</li><li>If <code>h exn</code> raises another exception <code>exn'</code>, <code>p_3</code> is rejected with <code>exn'</code>.</li><li>If <code>h exn</code> instead returns the promise <code>p_2</code>, <code>p_3</code> is effectively made into a reference to <code>p_2</code>. This means <code>p_3</code> and <code>p_2</code> have the same state, undergo the same state changes, and performing any operation one is equivalent to performing it on the other.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-finalize"><a href="#val-finalize" class="anchor"></a><code><span><span class="keyword">val</span> finalize : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span>)</span> <span class="arrow">-></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>Lwt.finalize f c</code> applies <code>f ()</code>, which returns a promise, and then makes it so <code>c</code> (“cleanup”) will run when that promise is <a href="#type-t" title="t"><em>resolved</em></a>.</p><p>In other words, <code>c</code> runs no matter whether promise <code>f ()</code> is fulfilled or rejected. As the names suggest, <code>Lwt.finalize</code> corresponds to the <code>finally</code> construct found in many programming languages, and <code>c</code> is typically used for cleaning up resources:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let%lwt file = Lwt_io.(open_file ~mode:Input "code.ml") in
|
||
Lwt.finalize
|
||
(fun () ->
|
||
let%lwt content = Lwt_io.read file in
|
||
Lwt_io.print content)
|
||
(fun () ->
|
||
Lwt_io.close file)
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>As with <a href="#val-bind"><code>Lwt.bind</code></a> and <a href="#val-catch"><code>Lwt.catch</code></a>, there is a syntactic sugar for <code>Lwt.finalize</code>, though it is not as often used:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
let%lwt file = Lwt_io.(open_file ~mode:Input "code.ml") in
|
||
begin
|
||
let%lwt content = Lwt_io.read file in
|
||
Lwt_io.print content
|
||
end
|
||
[%lwt.finally
|
||
Lwt_io.close file]
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>Also as with <a href="#val-bind"><code>Lwt.bind</code></a> and <a href="#val-catch"><code>Lwt.catch</code></a>, three promises are involved:</p><ul><li><code>p_1</code>, the promise returned from applying <code>f ()</code>.</li><li><code>p_2</code>, the promise returned from applying <code>c ()</code>.</li><li><code>p_3</code>, the promise returned by <code>Lwt.finalize</code> itself.</li></ul><p><code>p_3</code> is returned immediately. It starts out pending, and is resolved as follows:</p><ul><li><code>f ()</code> is applied. If it finishes, it will either return a promise <code>p_1</code>, or raise an exception.</li><li>If <code>f ()</code> raises an exception, <code>p_1</code> is created artificially as a promise rejected with that exception. So, no matter how <code>f ()</code> finishes, there is a promise <code>p_1</code> representing the outcome.</li><li>After <code>p_1</code> is resolved (fulfilled or rejected), <code>c ()</code> is applied. This is meant to be the cleanup code.</li><li>If <code>c ()</code> finishes, it will also either return a promise, <code>p_2</code>, or raise an exception.</li><li>If <code>c ()</code> raises an exception, <code>p_2</code> is created artificially as a promise rejected with that exception. Again, no matter how <code>c ()</code> finishes, there is a promise <code>p_2</code> representing the outcome of cleanup.</li><li>If <code>p_2</code> is fulfilled, <code>p_3</code> is resolved the same way <code>p_1</code> had been resolved. In other words, <code>p_1</code> is forwarded to <code>p_3</code> when cleanup is successful.</li><li>If <code>p_2</code> is rejected, <code>p_3</code> is rejected with the same exception. In other words, <code>p_2</code> is forwarded to <code>p_3</code> when cleanup is unsuccessful. Note this means that if <em>both</em> the protected code and the cleanup fail, the cleanup exception has precedence.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-try_bind"><a href="#val-try_bind" class="anchor"></a><code><span><span class="keyword">val</span> try_bind : <span><span>(<span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span>(<span>exn <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.try_bind f g h</code> applies <code>f ()</code>, and then makes it so that:</p><ul><li><code>g</code> will run when promise <code>f ()</code> is <a href="#type-t" title="t"><em>fulfilled</em></a>,</li><li><code>h</code> will run when promise <code>f ()</code> is <a href="#type-t" title="t"><em>rejected</em></a>.</li></ul><p><code>Lwt.try_bind</code> is a generalized <a href="#val-finalize"><code>Lwt.finalize</code></a>. The difference is that <code>Lwt.try_bind</code> runs different callbacks depending on <em>how</em> <code>f ()</code> is resolved. This has two main implications:</p><ul><li>The cleanup functions <code>g</code> and <code>h</code> each “know” whether <code>f ()</code> was fulfilled or rejected.</li><li>The cleanup functions <code>g</code> and <code>h</code> are passed the value <code>f ()</code> was fulfilled with, and, respectively, the exception <code>f ()</code> was rejected with.</li></ul><p>As with <a href="#val-catch"><code>Lwt.catch</code></a>, it is recommended to use <a href="#val-reraise"><code>reraise</code></a> in the catch-all case of the exception handler:</p><pre class="language-ocaml"><code>let () =
|
||
Lwt_main.run begin
|
||
Lwt.try_bind
|
||
(fun () -> raise Exit)
|
||
(fun () -> Lwt_io.printl "Got Success")
|
||
(function
|
||
| Exit -> Lwt_io.printl "Got Stdlib.Exit"
|
||
| exn -> Lwt.reraise exn)
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt.unix code.ml && ./a.out *)</code></pre><p>The rest is a detailed description of the promises involved.</p><p>As with <a href="#val-finalize"><code>Lwt.finalize</code></a> and the several preceding functions, three promises are involved.</p><ul><li><code>p_1</code> is the promise returned from applying <code>f ()</code>.</li><li><code>p_2</code> is the promise returned from applying <code>h</code> or <code>g</code>, depending on which one is chosen.</li><li><code>p_3</code> is the promise returned by <code>Lwt.try_bind</code> itself.</li></ul><p><code>Lwt.try_bind</code> returns <code>p_3</code> immediately. <code>p_3</code> starts out pending, and is resolved as follows:</p><ul><li><code>f ()</code> is applied. If it finishes, it either returns <code>p_1</code>, or raises an exception.</li><li>If <code>f ()</code> raises an exception, <code>p_1</code> is created artificially as a promise rejected with that exception. So, no matter how <code>f ()</code> finishes, there is a promise <code>p_1</code> representing the outcome.</li><li>If <code>p_1</code> is fulfilled, <code>g</code> is applied to the value <code>p_1</code> is fulfilled with.</li><li>If <code>p_1</code> is rejected, <code>h</code> is applied to the exception <code>p_1</code> is rejected with.</li><li>So, in either case, a callback is applied. The rest of the procedure is the same no matter which callback was chosen, so we will refer to it as “the callback.”</li><li>If the callback finishes, it either returns <code>p_2</code>, or raises an exception.</li><li>If the callback raises an exception, <code>p_3</code> is rejected with that exception.</li><li>If the callback returns <code>p_2</code>, <code>p_3</code> is effectively made into an reference to <code>p_2</code>. They have the same state, including any state changes, and performing any operation on one is equivalent to performing it on the other.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dont_wait"><a href="#val-dont_wait" class="anchor"></a><code><span><span class="keyword">val</span> dont_wait : <span><span>(<span>unit <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span>(<span>exn <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.dont_wait f handler</code> applies <code>f ()</code>, which returns a promise, and then makes it so that if the promise is <a href="#type-t" title="t"><em>rejected</em></a>, the exception is passed to <code>handler</code>.</p><p>In addition, if <code>f ()</code> raises an exception, it is also passed to <code>handler</code>.</p><p>As the name implies, <code>dont_wait (fun () -> <e>) handler</code> is a way to evaluate the expression <code><e></code> (which typically has asynchronous side-effects) <em>without waiting</em> for the resolution of the promise <code><e></code> evaluates to.</p><p><code>dont_wait</code> is meant as an alternative to <a href="#val-async"><code>async</code></a> with a local, explicit, predictable exception handler.</p><p>Note that <code>dont_wait f h</code> causes <code>f ()</code> to be evaluated immediately. Consequently, the non-yielding/non-pausing prefix of the body of <code>f</code> is evaluated immediately.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-async"><a href="#val-async" class="anchor"></a><code><span><span class="keyword">val</span> async : <span><span>(<span>unit <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.async f</code> applies <code>f ()</code>, which returns a promise, and then makes it so that if the promise is <a href="#type-t" title="t"><em>rejected</em></a>, the exception is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>.</p><p>In addition, if <code>f ()</code> raises an exception, it is also passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>.</p><p><code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a> typically prints an error message and terminates the program. If you need a similar behaviour with a different exception handler, you can use <a href="#val-dont_wait"><code>Lwt.dont_wait</code></a>.</p><p><code>Lwt.async</code> is misleadingly named. Itself, it has nothing to do with asynchronous execution. It's actually a safety function for making Lwt programs more debuggable.</p><p>For example, take this program, which prints messages in a loop, while waiting for one line of user input:</p><pre class="language-ocaml"><code>let () =
|
||
let rec show_nag () : _ Lwt.t =
|
||
let%lwt () = Lwt_io.printl "Please enter a line" in
|
||
let%lwt () = Lwt_unix.sleep 1. in
|
||
show_nag ()
|
||
in
|
||
ignore (show_nag ()); (* Bad – see note for (1)! *)
|
||
|
||
Lwt_main.run begin
|
||
let%lwt line = Lwt_io.(read_line stdin) in
|
||
Lwt_io.printl line
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>If one of the I/O operations in <code>show_nag</code> were to fail, the promise representing the whole loop would get rejected. However, since we are ignoring that promise at <b>(1)</b>, we never find out about the rejection. If this failure and resulting rejection represents a bug in the program, we have a harder time finding out about the bug.</p><p>A safer version differs only in using <code>Lwt.async</code> instead of <code>Stdlib.ignore</code>:</p><pre class="language-ocaml"><code>let () =
|
||
let rec show_nag () : _ Lwt.t =
|
||
let%lwt () = Lwt_io.printl "Please enter a line" in
|
||
let%lwt () = Lwt_unix.sleep 1. in
|
||
show_nag ()
|
||
in
|
||
Lwt.async (fun () -> show_nag ());
|
||
|
||
Lwt_main.run begin
|
||
let%lwt line = Lwt_io.(read_line stdin) in
|
||
Lwt_io.printl line
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>In this version, if I/O in <code>show_nag</code> fails with an exception, the exception is printed by <code>Lwt.async</code>, and then the program exits.</p><p>The general rule for when to use <code>Lwt.async</code> is:</p><ul><li>Promises which are <em>not</em> passed <em>to</em> <a href="#val-bind"><code>Lwt.bind</code></a>, <a href="#val-catch"><code>Lwt.catch</code></a>, <a href="#val-join"><code>Lwt.join</code></a>, etc., are <b>top-level</b> promises.</li><li>One top-level promise is passed to <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>, as can be seen in most examples in this manual.</li><li>Every other top-level promise should be wrapped in <code>Lwt.async</code>.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-async_exception_hook"><a href="#val-async_exception_hook" class="anchor"></a><code><span><span class="keyword">val</span> async_exception_hook : <span><span>(<span>exn <span class="arrow">-></span></span> unit)</span> <a href="../../ocaml/Stdlib/index.html#type-ref">Stdlib.ref</a></span></span></code></div><div class="spec-doc"><p>Reference to a function, to be called on an "unhandled" exception.</p><p>This reference is used by <a href="#val-async"><code>Lwt.async</code></a>, <a href="#val-on_cancel"><code>Lwt.on_cancel</code></a>, <a href="#val-on_success"><code>Lwt.on_success</code></a>, <a href="#val-on_failure"><code>Lwt.on_failure</code></a>, <a href="#val-on_termination"><code>Lwt.on_termination</code></a>, <a href="#val-on_any"><code>Lwt.on_any</code></a>, <code>Lwt_react.of_stream</code>, and the deprecated <a href="#val-ignore_result"><code>Lwt.ignore_result</code></a>.</p><p>The initial, default implementation prints the exception, then terminates the process with non-zero exit status, as if the exception had reached the top level of the program:</p><pre class="language-ocaml"><code>let () = Lwt.async (fun () -> raise Exit)
|
||
|
||
(* ocamlfind opt -linkpkg -package lwt code.ml && ./a.out *)</code></pre><p>produces in the output:</p><pre>Fatal error: exception Stdlib.Exit</pre><p>If you are writing an application, you are welcome to reassign the reference, and replace the function with something more appropriate for your needs.</p><p>If you are writing a library, you should leave this reference alone. Its behavior should be determined by the application.</p></div></div><h3 id="2_Concurrency"><a href="#2_Concurrency" class="anchor"></a>Concurrency</h3><h4 id="multiple-wait"><a href="#multiple-wait" class="anchor"></a>Multiple wait</h4><div class="odoc-spec"><div class="spec value anchored" id="val-both"><a href="#val-both" class="anchor"></a><code><span><span class="keyword">val</span> both : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.both p_1 p_2</code> returns a promise that is pending until <em>both</em> promises <code>p_1</code> and <code>p_2</code> become <a href="#type-t" title="t"><em>resolved</em></a>.</p><pre class="language-ocaml"><code>let () =
|
||
let p_1 =
|
||
let%lwt () = Lwt_unix.sleep 3. in
|
||
Lwt_io.printl "Three seconds elapsed"
|
||
in
|
||
|
||
let p_2 =
|
||
let%lwt () = Lwt_unix.sleep 5. in
|
||
Lwt_io.printl "Five seconds elapsed"
|
||
in
|
||
|
||
let p_3 = Lwt.both p_1 p_2 in
|
||
Lwt_main.run p_3
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>If both <code>p_1</code> and <code>p_2</code> become fulfilled, <code>Lwt.both p_1 p_2</code> is also fulfilled, with the pair of their final values. Otherwise, if at least one of the two promises becomes rejected, <code>Lwt.both p_1 p_2</code> is rejected with the same exception as one such promise, chosen arbitrarily. Note that this occurs only after both promises are resolved, not immediately when the first promise is rejected.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.2.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-join"><a href="#val-join" class="anchor"></a><code><span><span class="keyword">val</span> join : <span><span><span>unit <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.join ps</code> returns a promise that is pending until <em>all</em> promises in the list <code>ps</code> become <a href="#type-t" title="t"><em>resolved</em></a>.</p><pre class="language-ocaml"><code>let () =
|
||
let p_1 =
|
||
let%lwt () = Lwt_unix.sleep 3. in
|
||
Lwt_io.printl "Three seconds elapsed"
|
||
in
|
||
|
||
let p_2 =
|
||
let%lwt () = Lwt_unix.sleep 5. in
|
||
Lwt_io.printl "Five seconds elapsed"
|
||
in
|
||
|
||
let p_3 = Lwt.join [p_1; p_2] in
|
||
Lwt_main.run p_3
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>If all of the promises in <code>ps</code> become fulfilled, <code>Lwt.join ps</code> is also fulfilled. Otherwise, if at least one promise in <code>ps</code> becomes rejected, <code>Lwt.join ps</code> is rejected with the same exception as one such promise, chosen arbitrarily. Note that this occurs only after all the promises are resolved, not immediately when the first promise is rejected.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-all"><a href="#val-all" class="anchor"></a><code><span><span class="keyword">val</span> all : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.all ps</code> is like <a href="#val-join"><code>Lwt.join</code></a><code> ps</code>: it waits for all promises in the list <code>ps</code> to become <a href="#type-t" title="t"><em>resolved</em></a>.</p><p>It then resolves the returned promise with the list of all resulting values.</p><p>Note that if any of the promises in <code>ps</code> is rejected, the returned promise is also rejected. This means that none of the values will be available, even if some of the promises in <code>ps</code> were already resolved when one of them is rejected. For more fine-grained handling of rejection, structure the program with <a href="../Lwt_stream/index.html"><code>Lwt_stream</code></a> or <a href="../Lwt_list/index.html"><code>Lwt_list</code></a>, handle rejections explicitly, or use <a href="#val-join"><code>Lwt.join</code></a> and collect values manually.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 5.1.0</li></ul></div></div><h4 id="racing"><a href="#racing" class="anchor"></a>Racing</h4><div class="odoc-spec"><div class="spec value anchored" id="val-pick"><a href="#val-pick" class="anchor"></a><code><span><span class="keyword">val</span> pick : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></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>Lwt.pick ps</code> returns a promise that is pending until <em>one</em> promise in the list <code>ps</code> becomes <a href="#type-t" title="t"><em>resolved</em></a>.</p><p>When at least one promise in <code>ps</code> is resolved, <code>Lwt.pick</code> tries to cancel all other promises that are still pending, using <a href="#val-cancel"><code>Lwt.cancel</code></a>.</p><pre class="language-ocaml"><code>let () =
|
||
let echo =
|
||
let%lwt line = Lwt_io.(read_line stdin) in
|
||
Lwt_io.printl line
|
||
in
|
||
|
||
let timeout = Lwt_unix.sleep 5. in
|
||
|
||
Lwt_main.run (Lwt.pick [echo; timeout])
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>If the first promise in <code>ps</code> to become resolved is fulfilled, the result promise <code>p</code> is also fulfilled, with the same value. Likewise, if the first promise in <code>ps</code> to become resolved is rejected, <code>p</code> is rejected with the same exception.</p><p>If <code>ps</code> has no promises (if it is the empty list), <code>Lwt.pick ps</code> raises <code>Stdlib.Invalid_argument _</code>.</p><p>It's possible for multiple promises in <code>ps</code> to become resolved simultaneously. This happens most often when some promises <code>ps</code> are already resolved at the time <code>Lwt.pick</code> is called.</p><p>In that case, if at least one of the promises is rejected, the result promise <code>p</code> is rejected with the same exception as one such promise, chosen arbitrarily. If all promises are fulfilled, <code>p</code> is fulfilled with the value of one of the promises, also chosen arbitrarily.</p><p>The remaining functions in this section are variations on <code>Lwt.pick</code>.</p></div></div><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">-></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>Lwt.choose ps</code> is the same as <a href="#val-pick"><code>Lwt.pick</code></a><code> ps</code>, except that it does not try to cancel pending promises in <code>ps</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-npick"><a href="#val-npick" class="anchor"></a><code><span><span class="keyword">val</span> npick : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.npick ps</code> is similar to <a href="#val-pick"><code>Lwt.pick</code></a><code> ps</code>, the difference being that when multiple promises in <code>ps</code> are fulfilled simultaneously (and none are rejected), the result promise is fulfilled with the <em>list</em> of values the promises were fulfilled with.</p><p>When at least one promise is rejected, <code>Lwt.npick</code> still rejects the result promise with the same exception.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nchoose"><a href="#val-nchoose" class="anchor"></a><code><span><span class="keyword">val</span> nchoose : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.nchoose ps</code> is the same as <a href="#val-npick"><code>Lwt.npick</code></a><code> ps</code>, except that it does not try to cancel pending promises in <code>ps</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nchoose_split"><a href="#val-nchoose_split" class="anchor"></a><code><span><span class="keyword">val</span> nchoose_split : <span><span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> list</span> * <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> list</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.nchoose_split ps</code> is the same as <a href="#val-nchoose"><code>Lwt.nchoose</code></a><code> ps</code>, except that when multiple promises in <code>ps</code> are fulfilled simultaneously (and none are rejected), the result promise is fulfilled with <em>both</em> the list of values of the fulfilled promises, and the list of promises that are still pending.</p></div></div><h3 id="2_Cancellation"><a href="#2_Cancellation" class="anchor"></a>Cancellation</h3><p>Note: cancelation has proved difficult to understand, explain, and maintain, so use of these functions is discouraged in new code. See <a href="https://github.com/ocsigen/lwt/issues/283#issuecomment-518014539">ocsigen/lwt#283</a>.</p><div class="odoc-spec"><div class="spec exception anchored" id="exception-Canceled"><a href="#exception-Canceled" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Canceled</span></span></code></div><div class="spec-doc"><p>Canceled promises are those rejected with this exception, <code>Lwt.Canceled</code>. See <a href="#val-cancel"><code>Lwt.cancel</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-task"><a href="#val-task" class="anchor"></a><code><span><span class="keyword">val</span> task : <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span><span class="type-var">'a</span> <a href="#type-u">u</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.task</code> is the same as <a href="#val-wait"><code>Lwt.wait</code></a>, except the resulting promise <code>p</code> is <a href="#val-cancel" title="Lwt.cancel">cancelable</a>.</p><p>This is significant, because it means promises created by <code>Lwt.task</code> can be resolved (specifically, rejected) by canceling them directly, in addition to being resolved through their paired resolvers.</p><p>In contrast, promises returned by <a href="#val-wait"><code>Lwt.wait</code></a> can only be resolved through their resolvers.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cancel"><a href="#val-cancel" class="anchor"></a><code><span><span class="keyword">val</span> cancel : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.cancel p</code> attempts to <em>cancel</em> the pending promise <code>p</code>, without needing access to its resolver.</p><p>It is recommended to avoid <code>Lwt.cancel</code>, and handle cancelation by tracking the needed extra state explicitly within your library or application.</p><p>A <b>canceled</b> promise is one that has been rejected with exception <a href="#exception-Canceled"><code>Lwt.Canceled</code></a>.</p><p>There are straightforward ways to make promises canceled. One could create a promise that <em>starts out</em> canceled, with <a href="#val-fail"><code>Lwt.fail</code></a><code> Lwt.Canceled</code>. It's also possible to <em>make</em> a promise canceled through its resolver, by calling <a href="#val-wakeup_later_exn"><code>Lwt.wakeup_later_exn</code></a><code> r Lwt.Canceled</code>.</p><p>This function, <code>Lwt.cancel</code>, provides another method, which can cancel pending promises <em>without</em> going through their resolvers – it acts directly on promises.</p><p>Like any other promise rejection, the canceled state of a promise is propagated “forwards” by <a href="#val-bind"><code>Lwt.bind</code></a>, <a href="#val-join"><code>Lwt.join</code></a>, etc., as described in the documentation of those functions.</p><p><b>Cancellation</b> is a separate phase, triggered only by <a href="#val-cancel"><code>Lwt.cancel</code></a>, that searches <em>backwards</em>, strating from <code>p</code>, for promises to reject with <a href="#exception-Canceled"><code>Lwt.Canceled</code></a>. Once those promises are found, they are canceled, and then ordinary, forwards rejection propagation takes over.</p><p>All of this will be made precise, but first let's have an example:</p><pre class="language-ocaml"><code>let () =
|
||
let p =
|
||
let%lwt () = Lwt_unix.sleep 5. in
|
||
Lwt_io.printl "Slept five seconds"
|
||
in
|
||
|
||
Lwt.cancel p;
|
||
|
||
Lwt_main.run p
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>At the time <code>Lwt.cancel</code> is called, <code>p</code> “depends” on the <code>sleep</code> promise (the <code>printl</code> is not yet called, so its promise hasn't been created).</p><p>So, <a href="#val-cancel"><code>Lwt.cancel</code></a> recursively tries to cancel the <code>sleep</code> promise. That is an example of the backwards search. The <code>sleep</code> promise is a pending promise that doesn't depend on anything, so backwards search stops at it. The state of the <code>sleep</code> promise is set to <em>rejected</em> with <a href="#exception-Canceled"><code>Lwt.Canceled</code></a>.</p><p><a href="#val-bind"><code>Lwt.bind</code></a> then propagates the rejection forwards to <code>p</code>, so <code>p</code> also becomes canceled.</p><p>Eventually, this rejection reaches <a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a>, which raises the <a href="#exception-Canceled"><code>Lwt.Canceled</code></a> as an ordinary exception. The <code>sleep</code> does not complete, and the <code>printl</code> is never started.</p><p>Promises, like the <code>sleep</code> promise above, that can be rejected by <code>Lwt.cancel</code> are <b>cancelable</b>. Most promises in Lwt are either cancelable, or depend on cancelable promises. The functions <a href="#val-wait"><code>Lwt.wait</code></a> and <a href="#val-no_cancel"><code>Lwt.no_cancel</code></a> create promises that are <em>not</em> cancelable.</p><p>The rest is a detailed description of how the <code>Lwt.cancel</code> backwards search works.</p><ul><li>If <code>p</code> is already resolved, <code>Lwt.cancel</code> does nothing.</li><li>If <code>p</code> was created by <a href="#val-wait"><code>Lwt.wait</code></a> or <a href="#val-no_cancel"><code>Lwt.no_cancel</code></a>, <code>Lwt.cancel</code> does nothing.</li><li>If <code>p</code> was created by <a href="#val-task"><code>Lwt.task</code></a> or <a href="#val-protected"><code>Lwt.protected</code></a>, <code>Lwt.cancel</code> rejects it with <code>Lwt.Canceled</code>. This rejection then propagates normally through any Lwt calls that depend on <code>p</code>. Most I/O promises are internally created by calling <a href="#val-task"><code>Lwt.task</code></a>.</li><li>Suppose <code>p_3</code> was returned by <a href="#val-bind"><code>Lwt.bind</code></a>, <a href="#val-map"><code>Lwt.map</code></a>, <a href="#val-catch"><code>Lwt.catch</code></a>, <a href="#val-finalize"><code>Lwt.finalize</code></a>, or <a href="#val-try_bind"><code>Lwt.try_bind</code></a>. Then, see those functions for the naming of the other promises involved. If <code>p_3</code> is pending, then either <code>p_1</code> is pending, or <code>p_2</code> is pending. <code>Lwt.cancel p_3</code> then tries recursively to cancel whichever of these two is still pending. If that succeeds, <code>p_3</code> <em>may</em> be canceled later by the normal propagation of rejection.</li><li>Suppose <code>p</code> was returned by <a href="#val-join"><code>Lwt.join</code></a>, <a href="#val-pick"><code>Lwt.pick</code></a>, or similar function, which was applied to the promise list <code>ps</code>. <a href="#val-cancel"><code>Lwt.cancel</code></a> then recursively tries to cancel each promise in <code>ps</code>. If one of those cancellations succeeds, <code>p</code> <em>may</em> be canceled later by the normal propagation of rejection.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_cancel"><a href="#val-on_cancel" class="anchor"></a><code><span><span class="keyword">val</span> on_cancel : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.on_cancel p f</code> makes it so that <code>f</code> will run when <code>p</code> becomes <a href="#EXCEPTIONCanceled"><em>canceled</em></a>.</p><p>Callbacks scheduled with <code>on_cancel</code> are guaranteed to run before any other callbacks that are triggered by rejection, such as those added by <a href="#val-catch"><code>Lwt.catch</code></a>.</p><p>Note that this does not interact directly with the <em>cancellation</em> mechanism, the backwards search described in <a href="#val-cancel"><code>Lwt.cancel</code></a>. For example, manually rejecting a promise with <a href="#exception-Canceled"><code>Lwt.Canceled</code></a> is sufficient to trigger <code>f</code>.</p><p><code>f</code> should not raise exceptions. If it does, they are passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>, which terminates the process by default.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-protected"><a href="#val-protected" class="anchor"></a><code><span><span class="keyword">val</span> protected : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></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>Lwt.protected p</code> creates a <a href="#val-cancel" title="Lwt.cancel">cancelable</a> promise <code>p'</code>. The original state of <code>p'</code> is the same as the state of <code>p</code> at the time of the call.</p><p>The state of <code>p'</code> can change in one of two ways: a. if <code>p</code> changes state (i.e., is resolved), then <code>p'</code> eventually changes state to match <code>p</code>'s, and b. during cancellation, if the backwards search described in <a href="#val-cancel"><code>Lwt.cancel</code></a> reaches <code>p'</code> then it changes state to rejected <code>Canceled</code> and the search stops.</p><p>As a consequence of the b. case, <code>Lwt.cancel (protected p)</code> does not cancel <code>p</code>.</p><p>The promise <code>p</code> can still be canceled either directly (through <code>Lwt.cancel p</code>) or being reached by the backwards cancellation search via another path. <code>Lwt.protected</code> only prevents cancellation of <code>p</code> through <code>p'</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_cancel"><a href="#val-no_cancel" class="anchor"></a><code><span><span class="keyword">val</span> no_cancel : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></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>Lwt.no_cancel p</code> creates a non-<a href="#val-cancel" title="Lwt.cancel">cancelable</a> promise <code>p'</code>. The original state of <code>p'</code> is the same as <code>p</code> at the time of the call.</p><p>If the state of <code>p</code> changes, then the state of <code>p'</code> eventually changes too to match <code>p</code>'s.</p><p>Note that even though <code>p'</code> is non-<a href="#val-cancel" title="Lwt.cancel">cancelable</a>, it can still become canceled if <code>p</code> is canceled. <code>Lwt.no_cancel</code> only prevents cancellation of <code>p</code> and <code>p'</code> through <code>p'</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap_in_cancelable"><a href="#val-wrap_in_cancelable" class="anchor"></a><code><span><span class="keyword">val</span> wrap_in_cancelable : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></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>Lwt.wrap_in_cancelable p</code> creates a <a href="#val-cancel" title="Lwt.cancel">cancelable</a> promise <code>p'</code>. The original state of <code>p'</code> is the same as <code>p</code>.</p><p>The state of <code>p'</code> can change in one of two ways: a. if <code>p</code> changes state (i.e., is resolved), then <code>p'</code> eventually changes state to match <code>p</code>'s, and b. during cancellation, if the backwards search described in <a href="#val-cancel"><code>Lwt.cancel</code></a> reaches <code>p'</code> then it changes state to rejected <code>Canceled</code> and the search continues to <code>p</code>.</p></div></div><h4 id="cancellation-tweaks"><a href="#cancellation-tweaks" class="anchor"></a>Cancellation tweaks</h4><p>The primitives <code>protected</code>, <code>no_cancel</code>, and <code>wrap_in_cancelable</code> give you some level of control over the cancellation mechanism of Lwt. Note that promises passed as arguments to either of these three functions are unchanged. The functions return new promises with a specific cancellation behaviour.</p><p>The three behaviour of all three functions are summarised in the following table.</p><pre class="language-ocaml"><code>+----------------------------+--------------------+--------------------+
|
||
| setup - action | cancel p | cancel p' |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is cancelable | p is canceled | p is not canceled |
|
||
| p' = protected p | p' is canceled | p' is canceled |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is not cancelable | p is not canceled | p is not canceled |
|
||
| p' = protected p | p' is not canceled | p' is canceled |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is cancelable | p is canceled | p is not canceled |
|
||
| p' = no_cancel p | p' is canceled | p' is not canceled |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is not cancelable | p is not canceled | p is not canceled |
|
||
| p' = no_cancel p | p' is not canceled | p' is not canceled |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is cancelable | p is canceled | p is canceled |
|
||
| p' = wrap_in_cancelable p | p' is canceled | p' is canceled |
|
||
+----------------------------+--------------------+--------------------+
|
||
| p is not cancelable | p is not canceled | p is not canceled |
|
||
| p' = wrap_in_cancelable p | p' is not canceled | p' is canceled |
|
||
+----------------------------+--------------------+--------------------+</code></pre><h3 id="2_Convenience"><a href="#2_Convenience" class="anchor"></a>Convenience</h3><h4 id="callback-helpers"><a href="#callback-helpers" class="anchor"></a>Callback helpers</h4><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">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.map f p_1</code> is similar to <a href="#val-bind"><code>Lwt.bind</code></a><code> p_1 f</code>, but <code>f</code> is not expected to return a promise.</p><p>This function is more convenient than <a href="#val-bind"><code>Lwt.bind</code></a> when <code>f</code> inherently does not return a promise. An example is <code>Stdlib.int_of_string</code>:</p><pre class="language-ocaml"><code>let read_int : unit -> int Lwt.t = fun () ->
|
||
Lwt.map
|
||
int_of_string
|
||
Lwt_io.(read_line stdin)
|
||
|
||
let () =
|
||
Lwt_main.run begin
|
||
let%lwt number = read_int () in
|
||
Lwt_io.printf "%i\n" number
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>By comparison, the <a href="#val-bind"><code>Lwt.bind</code></a> version is more awkward:</p><pre class="language-ocaml"><code>let read_int : unit -> int Lwt.t = fun () ->
|
||
Lwt.bind
|
||
Lwt_io.(read_line stdin)
|
||
(fun line -> Lwt.return (int_of_string line))</code></pre><p>As with <a href="#val-bind"><code>Lwt.bind</code></a>, sequences of calls to <code>Lwt.map</code> result in excessive indentation and parentheses. The recommended syntactic sugar for avoiding this is the <a href="Infix/index.html#val-(>|=)" title="Lwt.Infix.(>|=)"><code>>|=</code></a> operator, which comes from module <code>Lwt.Infix</code>:</p><pre class="language-ocaml"><code>open Lwt.Infix
|
||
|
||
let read_int : unit -> int Lwt.t = fun () ->
|
||
Lwt_io.(read_line stdin) >|= int_of_string</code></pre><p>The detailed operation follows. For consistency with the promises in <a href="#val-bind"><code>Lwt.bind</code></a>, the <em>two</em> promises involved are named <code>p_1</code> and <code>p_3</code>:</p><ul><li><code>p_1</code> is the promise passed to <code>Lwt.map</code>.</li><li><code>p_3</code> is the promise returned by <code>Lwt.map</code>.</li></ul><p><code>Lwt.map</code> returns a promise <code>p_3</code>. <code>p_3</code> starts out pending. It is resolved as follows:</p><ul><li><code>p_1</code> may be, or become, resolved. In that case, by definition, it will become fulfilled or rejected. Fulfillment is the interesting case, but the behavior on rejection is simpler, so we focus on rejection first.</li><li>When <code>p_1</code> becomes rejected, <code>p_3</code> is rejected with the same exception.</li><li>When <code>p_1</code> instead becomes fulfilled, call the value it is fulfilled with <code>v</code>.</li><li><code>f v</code> is applied. If this finishes, it may either return another value, or raise an exception.</li><li>If <code>f v</code> returns another value <code>v'</code>, <code>p_3</code> is fulfilled with <code>v'</code>.</li><li>If <code>f v</code> raises exception <code>exn</code>, <code>p_3</code> is rejected with <code>exn</code>.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_success"><a href="#val-on_success" class="anchor"></a><code><span><span class="keyword">val</span> on_success : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.on_success p f</code> makes it so that <code>f</code> will run when <code>p</code> is <a href="#type-t" title="t"><em>fulfilled</em></a>.</p><p>It is similar to <a href="#val-bind"><code>Lwt.bind</code></a>, except no new promises are created. <code>f</code> is a plain, arbitrary function attached to <code>p</code>, to perform some side effect.</p><p>If <code>f</code> raises an exception, it is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>. By default, this will terminate the process.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_failure"><a href="#val-on_failure" class="anchor"></a><code><span><span class="keyword">val</span> on_failure : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span>exn <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.on_failure p f</code> makes it so that <code>f</code> will run when <code>p</code> is <a href="#type-t" title="t"><em>rejected</em></a>.</p><p>It is similar to <a href="#val-catch"><code>Lwt.catch</code></a>, except no new promises are created.</p><p>If <code>f</code> raises an exception, it is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>. By default, this will terminate the process.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_termination"><a href="#val-on_termination" class="anchor"></a><code><span><span class="keyword">val</span> on_termination : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.on_termination p f</code> makes it so that <code>f</code> will run when <code>p</code> is <a href="#type-t" title="t"><em>resolved</em></a> – that is, fulfilled <em>or</em> rejected.</p><p>It is similar to <a href="#val-finalize"><code>Lwt.finalize</code></a>, except no new promises are created.</p><p>If <code>f</code> raises an exception, it is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>. By default, this will terminate the process.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-on_any"><a href="#val-on_any" class="anchor"></a><code><span><span class="keyword">val</span> on_any : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> <span><span>(<span>exn <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.on_any p f g</code> makes it so that:</p><ul><li><code>f</code> will run when <code>p</code> is <a href="#type-t" title="t"><em>fulfilled</em></a>,</li><li><code>g</code> will run when <code>p</code> is, alternatively, <a href="#type-t" title="t"><em>rejected</em></a>.</li></ul><p>It is similar to <a href="#val-try_bind"><code>Lwt.try_bind</code></a>, except no new promises are created.</p><p>If <code>f</code> or <code>g</code> raise an exception, the exception is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>. By default, this will terminate the process.</p></div></div><h4 id="infix-operators"><a href="#infix-operators" class="anchor"></a>Infix operators</h4><div class="odoc-spec"><div class="spec module anchored" id="module-Infix"><a href="#module-Infix" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Infix/index.html">Infix</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>This module provides several infix operators for making programming with Lwt more convenient.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Let_syntax"><a href="#module-Let_syntax" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Let_syntax/index.html">Let_syntax</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Syntax"><a href="#module-Syntax" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Syntax/index.html">Syntax</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h4 id="pre-allocated-promises"><a href="#pre-allocated-promises" class="anchor"></a>Pre-allocated promises</h4><div class="odoc-spec"><div class="spec value anchored" id="val-return_unit"><a href="#val-return_unit" class="anchor"></a><code><span><span class="keyword">val</span> return_unit : <span>unit <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.return_unit</code> is defined as <a href="#val-return"><code>Lwt.return</code></a><code> ()</code>, but this definition is evaluated only once, during initialization of module <code>Lwt</code>, at the beginning of your program.</p><p>This means the promise is allocated only once. By contrast, each time <a href="#val-return"><code>Lwt.return</code></a><code> ()</code> is evaluated, it allocates a new promise.</p><p>It is recommended to use <code>Lwt.return_unit</code> only where you know the allocations caused by an instance of <a href="#val-return"><code>Lwt.return</code></a><code> ()</code> are a performance bottleneck. Generally, the cost of I/O tends to dominate the cost of <a href="#val-return"><code>Lwt.return</code></a><code> ()</code> anyway.</p><p>In future Lwt, we hope to perform this optimization, of using a single, pre-allocated promise, automatically, wherever <a href="#val-return"><code>Lwt.return</code></a><code> ()</code> is written.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_none"><a href="#val-return_none" class="anchor"></a><code><span><span class="keyword">val</span> return_none : <span><span><span class="type-var">_</span> option</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.return_none</code> is like <a href="#val-return_unit"><code>Lwt.return_unit</code></a>, but for <a href="#val-return"><code>Lwt.return</code></a><code> None</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_nil"><a href="#val-return_nil" class="anchor"></a><code><span><span class="keyword">val</span> return_nil : <span><span><span class="type-var">_</span> list</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.return_nil</code> is like <a href="#val-return_unit"><code>Lwt.return_unit</code></a>, but for <a href="#val-return"><code>Lwt.return</code></a><code> []</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_true"><a href="#val-return_true" class="anchor"></a><code><span><span class="keyword">val</span> return_true : <span>bool <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.return_true</code> is like <a href="#val-return_unit"><code>Lwt.return_unit</code></a>, but for <a href="#val-return"><code>Lwt.return</code></a><code> true</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_false"><a href="#val-return_false" class="anchor"></a><code><span><span class="keyword">val</span> return_false : <span>bool <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.return_false</code> is like <a href="#val-return_unit"><code>Lwt.return_unit</code></a>, but for <a href="#val-return"><code>Lwt.return</code></a><code> false</code>.</p></div></div><h4 id="trivial-promises"><a href="#trivial-promises" class="anchor"></a>Trivial promises</h4><div class="odoc-spec"><div class="spec value anchored" id="val-return_some"><a href="#val-return_some" class="anchor"></a><code><span><span class="keyword">val</span> return_some : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Counterpart to <a href="#val-return_none"><code>Lwt.return_none</code></a>. However, unlike <a href="#val-return_none"><code>Lwt.return_none</code></a>, this function performs no <a href="#VALreturn_unit">optimization</a>. This is because it takes an argument, so it cannot be evaluated at initialization time, at which time the argument is not yet available.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_ok"><a href="#val-return_ok" class="anchor"></a><code><span><span class="keyword">val</span> return_ok : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'a</span>, <span class="type-var">_</span>)</span> <a href="../../ocaml/Stdlib/index.html#type-result">Stdlib.result</a></span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Like <a href="#val-return_some"><code>Lwt.return_some</code></a>, this function performs no optimization.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> Lwt 2.6.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-return_error"><a href="#val-return_error" class="anchor"></a><code><span><span class="keyword">val</span> return_error : <span><span class="type-var">'e</span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">_</span>, <span class="type-var">'e</span>)</span> <a href="../../ocaml/Stdlib/index.html#type-result">Stdlib.result</a></span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Like <a href="#val-return_some"><code>Lwt.return_some</code></a>, this function performs no optimization.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> Lwt 2.6.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fail_with"><a href="#val-fail_with" class="anchor"></a><code><span><span class="keyword">val</span> fail_with : <span>string <span class="arrow">-></span></span> <span><span class="type-var">_</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.fail_with s</code> is an abbreviation for</p><pre class="language-ocaml"><code>Lwt.fail (Stdlib.Failure s)</code></pre><p>In most cases, it is better to use <code>failwith s</code> from the standard library. See <a href="#val-fail"><code>Lwt.fail</code></a> for an explanation.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fail_invalid_arg"><a href="#val-fail_invalid_arg" class="anchor"></a><code><span><span class="keyword">val</span> fail_invalid_arg : <span>string <span class="arrow">-></span></span> <span><span class="type-var">_</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.invalid_arg s</code> is an abbreviation for</p><pre class="language-ocaml"><code>Lwt.fail (Stdlib.Invalid_argument s)</code></pre><p>In most cases, it is better to use <code>invalid_arg s</code> from the standard library. See <a href="#val-fail"><code>Lwt.fail</code></a> for an explanation.</p></div></div><h4 id="result-type"><a href="#result-type" class="anchor"></a>Result type</h4><p>A resolved promise of type <code>'a </code><a href="#type-t"><code>Lwt.t</code></a> is either fulfilled with a value of type <code>'a</code>, or rejected with an exception.</p><p>This corresponds to the cases of a <code>('a, exn)</code><a href="../../ocaml/Stdlib/index.html#type-result"><code>Stdlib.result</code></a>: fulfilled corresponds to <code>Ok of 'a</code>, and rejected corresponds to <code>Error of exn</code>.</p><p>For Lwt programming with <code>result</code> where the <code>Error</code> constructor can carry arbitrary error types, see module <a href="../Lwt_result/index.html"><code>Lwt_result</code></a>.</p><div class="odoc-spec"><div class="spec value anchored" id="val-of_result"><a href="#val-of_result" class="anchor"></a><code><span><span class="keyword">val</span> of_result : <span><span><span>(<span class="type-var">'a</span>, exn)</span> <a href="../../ocaml/Stdlib/index.html#type-result">Stdlib.result</a></span> <span class="arrow">-></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>Lwt.of_result r</code> converts an r to a resolved promise.</p><ul><li>If <code>r</code> is <code>Ok v</code>, <code>Lwt.of_result r</code> is <code>Lwt.return v</code>, i.e. a promise fulfilled with <code>v</code>.</li><li>If <code>r</code> is <code>Error exn</code>, <code>Lwt.of_result r</code> is <code>Lwt.fail exn</code>, i.e. a promise rejected with <code>exn</code>.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup_later_result"><a href="#val-wakeup_later_result" class="anchor"></a><code><span><span class="keyword">val</span> wakeup_later_result : <span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'a</span>, exn)</span> <a href="../../ocaml/Stdlib/index.html#type-result">Stdlib.result</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup_later_result r result</code> resolves the pending promise <code>p</code> associated to resolver <code>r</code>, according to <code>result</code>:</p><ul><li>If <code>result</code> is <code>Ok v</code>, <code>p</code> is fulfilled with <code>v</code>.</li><li>If <code>result</code> is <code>Error exn</code>, <code>p</code> is rejected with <code>exn</code>.</li></ul><p>If <code>p</code> is not pending, <code>Lwt.wakeup_later_result</code> raises <code>Stdlib.Invalid_argument _</code>, except if <code>p</code> is <a href="#val-cancel" title="Lwt.cancel">canceled</a>. If <code>p</code> is canceled, <code>Lwt.wakeup_later_result</code> has no effect.</p></div></div><h4 id="state-query"><a href="#state-query" class="anchor"></a>State query</h4><div class="odoc-spec"><div class="spec type anchored" id="type-state"><a href="#type-state" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a state</span></span><span> = </span></code><ol><li id="type-state.Return" class="def variant constructor anchored"><a href="#type-state.Return" class="anchor"></a><code><span>| </span><span><span class="constructor">Return</span> <span class="keyword">of</span> <span class="type-var">'a</span></span></code></li><li id="type-state.Fail" class="def variant constructor anchored"><a href="#type-state.Fail" class="anchor"></a><code><span>| </span><span><span class="constructor">Fail</span> <span class="keyword">of</span> exn</span></code></li><li id="type-state.Sleep" class="def variant constructor anchored"><a href="#type-state.Sleep" class="anchor"></a><code><span>| </span><span><span class="constructor">Sleep</span></span></code></li></ol></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-state"><a href="#val-state" class="anchor"></a><code><span><span class="keyword">val</span> state : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-state">state</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.state p</code> evaluates to the current state of promise <code>p</code>:</p><ul><li>If <code>p</code> is <a href="#type-t" title="t">fulfilled</a> with value <code>v</code>, the result is <code>Lwt.Return v</code>.</li><li>If <code>p</code> is <a href="#type-t" title="t">rejected</a> with exception <code>exn</code>, the result is <code>Lwt.Fail exn</code>.</li><li>If <code>p</code> is <a href="#type-t" title="t">pending</a>, the result is <code>Lwt.Sleep</code>.</li></ul><p>The constructor names are historical holdovers.</p></div></div><h3 id="2_Deprecated"><a href="#2_Deprecated" class="anchor"></a>Deprecated</h3><h4 id="implicit-callback-arguments"><a href="#implicit-callback-arguments" class="anchor"></a>Implicit callback arguments</h4><p>Using this mechanism is discouraged, because it is non-syntactic, and because it manipulates hidden state in module <code>Lwt</code>. It is recommended instead to pass additional values explicitly in tuples, or maintain explicit associative maps for them.</p><div class="odoc-spec"><div class="spec type anchored" id="type-key"><a href="#type-key" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a key</span></span></code></div><div class="spec-doc"><p>Keys into the implicit callback argument map, for implicit arguments of type <code>'a option</code>.</p><p>The keys are abstract, but they are basically integers that are all distinct from each other.</p><p>See <a href="#val-with_value"><code>Lwt.with_value</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-new_key"><a href="#val-new_key" class="anchor"></a><code><span><span class="keyword">val</span> new_key : <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-key">key</a></span></span></code></div><div class="spec-doc"><p>Creates a fresh implicit callback argument key.</p><p>The key is distinct from any other key created by the current process. The value <code>None</code> of type <code>'a option</code> is immediately associated with the key.</p><p>See <a href="#val-with_value"><code>Lwt.with_value</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-key">key</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p>Retrieves the value currently associated with the given implicit callback argument key.</p><p>See <a href="#val-with_value"><code>Lwt.with_value</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_value"><a href="#val-with_value" class="anchor"></a><code><span><span class="keyword">val</span> with_value : <span><span><span class="type-var">'a</span> <a href="#type-key">key</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'b</span></span></code></div><div class="spec-doc"><p><code>Lwt.with_value k v f</code> sets <code>k</code> to <code>v</code> in Lwt's internal implicit callback argument map, then runs <code>f ()</code>, then restores the previous value associated with <code>k</code>.</p><p>Lwt maintains a single, global map, that can be used to “pass” extra arguments to callbacks:</p><pre class="language-ocaml"><code>let () =
|
||
let k : string Lwt.key = Lwt.new_key () in
|
||
|
||
let say_hello () =
|
||
match Lwt.get k with
|
||
| None -> assert false
|
||
| Some s -> Lwt_io.printl s
|
||
in
|
||
|
||
Lwt_main.run begin
|
||
Lwt.with_value k (Some "Hello world!") begin fun () ->
|
||
Lwt.bind
|
||
(Lwt_unix.sleep 1.)
|
||
(fun () -> say_hello ())
|
||
end
|
||
end
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>Note that the string <code>Hello world!</code> was passed to <code>say_hello</code> through the key <code>k</code>. Meanwhile, the only <em>explicit</em> argument of the callback <code>say_hello</code> is <code>()</code>.</p><p>The way this works is functions like <a href="#val-bind"><code>Lwt.bind</code></a> take a <b>snapshot</b> of the implicit argument map. Later, right before the callback is run, the map is <em>restored</em> to that snapshot. In other words, the map has the same state inside the callback as it did at the time the callback was registered.</p><p>To be more precise:</p><ul><li><code>Lwt.with_value</code> associates <code>Some "Hello world!"</code> with <code>k</code>, and runs the function passed to it.</li><li>This function contains the <a href="#val-bind"><code>Lwt.bind</code></a>.</li><li>OCaml's eager evaluation means the arguments are evaluated first. In particular, the <code>Lwt_unix.sleep 1.</code> promise is created.</li><li><a href="#val-bind"><code>Lwt.bind</code></a> then attaches the callback in its second argument, the one which calls <code>say_hello</code>, to that <code>sleep</code> promise.</li><li><a href="#val-bind"><code>Lwt.bind</code></a> also takes a snapshot of the current state of the implicit argument map, and pairs the callback with that snapshot.</li><li>The callback will not run for another second or so, when the <code>sleep</code> promise will be resolved.</li><li>Instead, <a href="#val-bind"><code>Lwt.bind</code></a> returns its result promise <code>p_3</code>. This causes <code>Lwt.with_value</code> to also return <code>p_3</code>, first restoring <code>k</code> to be associated with <code>None</code>.</li><li><a href="../Lwt_main/index.html#val-run"><code>Lwt_main.run</code></a> gets the pending <code>p_3</code>, and blocks the whole process, with <code>k</code> associated with <code>None</code>.</li><li>One second later, the <code>sleep</code> I/O completes, resolving the <code>sleep</code> promise.</li><li>This triggers the <code>say_hello</code> callback. Right before the callback is called, the implicit argument map is restored to its snapshot, so <code>k</code> is associated with <code>Some "Hello world!"</code>.</li><li>After the callback completes, Lwt again restores <code>k</code> to be associated with <code>None</code>.</li></ul><p>The Lwt functions that take snapshots of the implicit callback argument map are exactly those which attach callbacks to promises: <a href="#val-bind"><code>Lwt.bind</code></a> and its variants <code>>>=</code> and <code>let%lwt</code>, <a href="#val-map"><code>Lwt.map</code></a> and its variant <code>>|=</code>, <a href="#val-catch"><code>Lwt.catch</code></a> and its variant <code>try%lwt</code>, <a href="#val-finalize"><code>Lwt.finalize</code></a> and its variant <code>%lwt.finally</code>, <a href="#val-try_bind"><code>Lwt.try_bind</code></a>, <a href="#val-on_success"><code>Lwt.on_success</code></a>, <a href="#val-on_failure"><code>Lwt.on_failure</code></a>, <a href="#val-on_termination"><code>Lwt.on_termination</code></a>, and <a href="#val-on_any"><code>Lwt.on_any</code></a>.</p><p><code>Lwt.with_value</code> should only be called in the main thread, i.e. do not call it inside <a href="../Lwt_preemptive/index.html#val-detach"><code>Lwt_preemptive.detach</code></a>.</p></div></div><h4 id="immediate-resolving"><a href="#immediate-resolving" class="anchor"></a>Immediate resolving</h4><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup"><a href="#val-wakeup" class="anchor"></a><code><span><span class="keyword">val</span> wakeup : <span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup r v</code> is like <a href="#val-wakeup_later"><code>Lwt.wakeup_later</code></a><code> r v</code>, except it guarantees that callbacks associated with <code>r</code> will be called immediately, deeper on the current stack.</p><p>In contrast, <a href="#val-wakeup_later"><code>Lwt.wakeup_later</code></a> <em>may</em> call callbacks immediately, or may queue them for execution on a shallower stack – though still before the next time Lwt blocks the process on I/O.</p><p>Using this function is discouraged, because calling it in a loop can exhaust the stack. The loop might be difficult to detect or predict, due to combined mutually-recursive calls between multiple modules and libraries.</p><p>Also, trying to use this function to guarantee the timing of callback calls for synchronization purposes is discouraged. This synchronization effect is obscure to readers. It is better to use explicit promises, or <a href="../Lwt_mutex/index.html"><code>Lwt_mutex</code></a>, <a href="../Lwt_condition/index.html"><code>Lwt_condition</code></a>, and/or <a href="../Lwt_mvar/index.html"><code>Lwt_mvar</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup_exn"><a href="#val-wakeup_exn" class="anchor"></a><code><span><span class="keyword">val</span> wakeup_exn : <span><span><span class="type-var">_</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span>exn <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup_exn r exn</code> is like <a href="#val-wakeup_later_exn"><code>Lwt.wakeup_later_exn</code></a><code> r exn</code>, but has the same problems as <a href="#val-wakeup"><code>Lwt.wakeup</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wakeup_result"><a href="#val-wakeup_result" class="anchor"></a><code><span><span class="keyword">val</span> wakeup_result : <span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'a</span>, exn)</span> <a href="../../ocaml/Stdlib/index.html#type-result">Stdlib.result</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Lwt.wakeup_result r result</code> is like <a href="#val-wakeup_later_result"><code>Lwt.wakeup_later_result</code></a><code> r result</code>, but has the same problems as <a href="#val-wakeup"><code>Lwt.wakeup</code></a>.</p></div></div><h4 id="linked-lists-of-promises"><a href="#linked-lists-of-promises" class="anchor"></a>Linked lists of promises</h4><div class="odoc-spec"><div class="spec value anchored" id="val-add_task_r"><a href="#val-add_task_r" class="anchor"></a><code><span><span class="keyword">val</span> add_task_r : <span><span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <a href="../Lwt_sequence/index.html#type-t">Lwt_sequence.t</a></span> <span class="arrow">-></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>Lwt.add_task_r sequence</code> is equivalent to</p><pre class="language-ocaml"><code>let p, r = Lwt.task () in
|
||
let node = Lwt_sequence.add_r r sequence in
|
||
Lwt.on_cancel p (fun () -> Lwt_sequence.remove node);
|
||
p</code></pre><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>Use of this function is discouraged for two reasons:</p><ul><li><a href="../Lwt_sequence/index.html"><code>Lwt_sequence</code></a> should not be used outside Lwt.</li><li>This function only exists because it performs a minor internal optimization, which may be removed.</li></ul></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-add_task_l"><a href="#val-add_task_l" class="anchor"></a><code><span><span class="keyword">val</span> add_task_l : <span><span><span><span class="type-var">'a</span> <a href="#type-u">u</a></span> <a href="../Lwt_sequence/index.html#type-t">Lwt_sequence.t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Like <a href="#val-add_task_r"><code>Lwt.add_task_r</code></a>, but the equivalent code calls <a href="../Lwt_sequence/index.html#val-add_l"><code>Lwt_sequence.add_l</code></a> instead.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>See <code>add_task_r</code>.</p></li></ul></div></div><h4 id="yielding"><a href="#yielding" class="anchor"></a>Yielding</h4><div class="odoc-spec"><div class="spec value anchored" id="val-pause"><a href="#val-pause" class="anchor"></a><code><span><span class="keyword">val</span> pause : <span>unit <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>Lwt.pause ()</code> creates a pending promise that is fulfilled after Lwt finishes calling all currently ready callbacks, i.e. it is fulfilled on the next “tick.”</p><p>Putting the rest of your computation into a callback of <code>Lwt.pause ()</code> creates a “yield” that gives other callbacks a chance to run first.</p><p>For example, to break up a long-running computation, allowing I/O to be handled between chunks:</p><pre class="language-ocaml"><code>let () =
|
||
let rec handle_io () =
|
||
let%lwt () = Lwt_io.printl "Handling I/O" in
|
||
let%lwt () = Lwt_unix.sleep 0.1 in
|
||
handle_io ()
|
||
in
|
||
|
||
let rec compute n =
|
||
if n = 0 then
|
||
Lwt.return ()
|
||
else
|
||
let%lwt () =
|
||
if n mod 1_000_000 = 0 then
|
||
Lwt.pause ()
|
||
else
|
||
Lwt.return ()
|
||
in
|
||
compute (n - 1)
|
||
in
|
||
|
||
Lwt.async handle_io;
|
||
Lwt_main.run (compute 100_000_000)
|
||
|
||
(* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)</code></pre><p>If you replace the call to <code>Lwt.pause</code> by <code>Lwt.return</code> in the program above, <code>"Handling I/O"</code> is printed only once. With <code>Lwt.pause</code>, it is printed several times, depending on the speed of your machine.</p><p>An alternative way to handle long-running computations is to detach them to preemptive threads using <a href="../Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a>.</p></div></div><h4 id="function-lifters"><a href="#function-lifters" class="anchor"></a>Function lifters</h4><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>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></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>Lwt.wrap f</code> applies <code>f ()</code>. If <code>f ()</code> returns a value <code>v</code>, <code>Lwt.wrap</code> returns <a href="#val-return"><code>Lwt.return</code></a><code> v</code>. If <code>f ()</code> raises an exception exn, <code>Lwt.wrap</code> returns <a href="#val-fail"><code>Lwt.fail</code></a><code> exn</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap1"><a href="#val-wrap1" class="anchor"></a><code><span><span class="keyword">val</span> wrap1 : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap2"><a href="#val-wrap2" class="anchor"></a><code><span><span class="keyword">val</span> wrap2 : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span class="type-var">'c</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap3"><a href="#val-wrap3" class="anchor"></a><code><span><span class="keyword">val</span> wrap3 : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span class="type-var">'d</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap4"><a href="#val-wrap4" class="anchor"></a><code><span><span class="keyword">val</span> wrap4 : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <span class="arrow">-></span></span> <span class="type-var">'e</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <span class="arrow">-></span></span> <span><span class="type-var">'e</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap5"><a href="#val-wrap5" class="anchor"></a><code><span><span class="keyword">val</span> wrap5 :
|
||
<span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <span class="arrow">-></span></span> <span><span class="type-var">'e</span> <span class="arrow">-></span></span> <span class="type-var">'f</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'b</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'c</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'d</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'e</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'f</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap6"><a href="#val-wrap6" class="anchor"></a><code><span><span class="keyword">val</span> wrap6 :
|
||
<span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <span class="arrow">-></span></span> <span><span class="type-var">'e</span> <span class="arrow">-></span></span> <span><span class="type-var">'f</span> <span class="arrow">-></span></span> <span class="type-var">'g</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'b</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'c</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'d</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'e</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'f</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'g</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wrap7"><a href="#val-wrap7" class="anchor"></a><code><span><span class="keyword">val</span> wrap7 :
|
||
<span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> <span><span class="type-var">'c</span> <span class="arrow">-></span></span> <span><span class="type-var">'d</span> <span class="arrow">-></span></span> <span><span class="type-var">'e</span> <span class="arrow">-></span></span> <span><span class="type-var">'f</span> <span class="arrow">-></span></span> <span><span class="type-var">'g</span> <span class="arrow">-></span></span> <span class="type-var">'h</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'b</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'c</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'d</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'e</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'f</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'g</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'h</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>As a “prototype,” <code>Lwt_wrap1 f</code> creates a promise-valued function <code>g</code>:</p><pre class="language-ocaml"><code>let g v =
|
||
try
|
||
let v' = f v in
|
||
Lwt.return v'
|
||
with exn ->
|
||
Lwt.fail exn</code></pre><p>The remainder of the functions work analogously – they just work on <code>f</code> with larger numbers of arguments.</p><p>Note that there is an important difference to <a href="#val-wrap"><code>Lwt.wrap</code></a>. These functions don't run <code>f</code>, nor create the final promise, immediately. In contrast, <a href="#val-wrap"><code>Lwt.wrap</code></a> runs its argument <code>f</code> eagerly.</p><p>To get a suspended function instead of the eager execution of <a href="#val-wrap"><code>Lwt.wrap</code></a>, use <code>Lwt.wrap1</code>.</p></div></div><h4 id="unscoped-infix-operators"><a href="#unscoped-infix-operators" class="anchor"></a>Unscoped infix operators</h4><p>Use the operators in module <a href="Infix/index.html"><code>Lwt.Infix</code></a> instead. Using these instances of the operators directly requires opening module <code>Lwt</code>, which brings an excessive number of other names into scope.</p><div class="odoc-spec"><div class="spec value anchored" id="val-(>>=)"><a href="#val-(>>=)" class="anchor"></a><code><span><span class="keyword">val</span> (>>=) : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(>|=)"><a href="#val-(>|=)" class="anchor"></a><code><span><span class="keyword">val</span> (>|=) : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(<?>)"><a href="#val-(<?>)" class="anchor"></a><code><span><span class="keyword">val</span> (<?>) : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(<&>)"><a href="#val-(<&>)" class="anchor"></a><code><span><span class="keyword">val</span> (<&>) : <span><span>unit <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>unit <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>unit <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(=<<)"><a href="#val-(=<<)" class="anchor"></a><code><span><span class="keyword">val</span> (=<<) : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(=|<)"><a href="#val-(=|<)" class="anchor"></a><code><span><span class="keyword">val</span> (=|<) : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div></div><h4 id="miscellaneous"><a href="#miscellaneous" class="anchor"></a>Miscellaneous</h4><div class="odoc-spec"><div class="spec value anchored" id="val-is_sleeping"><a href="#val-is_sleeping" class="anchor"></a><code><span><span class="keyword">val</span> is_sleeping : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>Lwt.is_sleeping p</code> is equivalent to <a href="#val-state"><code>Lwt.state</code></a><code> p = Lwt.Sleep</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-ignore_result"><a href="#val-ignore_result" class="anchor"></a><code><span><span class="keyword">val</span> ignore_result : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>An obsolete variant of <a href="#val-async"><code>Lwt.async</code></a>.</p><p><code>Lwt.ignore_result p</code> behaves as follows:</p><ul><li>If <code>p</code> is already fulfilled, <code>Lwt.ignore_result p</code> does nothing.</li><li>If <code>p</code> is already rejected with <code>exn</code>, <code>Lwt.ignore_result p</code> raises <code>exn</code> immediately.</li><li>If <code>p</code> is pending, <code>Lwt.ignore_result p</code> does nothing, but if <code>p</code> becomes rejected later, the exception is passed to <code>!</code><a href="#val-async_exception_hook"><code>Lwt.async_exception_hook</code></a>.</li></ul><p>Use of this function is discouraged for two reasons:</p><ul><li>The behavior is different depending on whether <code>p</code> is rejected now or later.</li><li>The name is misleading, and has led to users thinking this function is analogous to <a href="../../ocaml/Stdlib/index.html#val-ignore"><code>Stdlib.ignore</code></a>, i.e. that it waits for <code>p</code> to become resolved, completing any associated side effects along the way. In fact, the function that does <em>that</em> is ordinary <a href="#val-bind"><code>Lwt.bind</code></a>.</li></ul></div></div><h5 id="runtime-exception-filters"><a href="#runtime-exception-filters" class="anchor"></a>Runtime exception filters</h5><p>Depending on the kind of programs that you write, you may need to treat exceptions thrown by the OCaml runtime (namely <code>Out_of_memory</code> and <code>Stack_overflow</code>) differently than all the other exceptions. This is because (a) these exceptions are not reproducible (in that they are thrown at different points of your program depending on the machine that your program runs on) and (b) recovering from these errors may be impossible.</p><p>The helpers below allow you to change the way that Lwt handles the two OCaml runtime exceptions <code>Out_of_memory</code> and <code>Stack_overflow</code>.</p><div class="odoc-spec"><div class="spec module anchored" id="module-Exception_filter"><a href="#module-Exception_filter" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Exception_filter/index.html">Exception_filter</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div></div></body></html>
|