package spin

Promises for values of type 'a.

A promise is a memory cell that is always in one of three states:

• fulfilled, and containing one value of type 'a,
• rejected, and containing one exception, or
• pending, in which case it may become fulfilled or rejected later.

A resolved 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 write-once references. The only possible state changes are (1) from pending to fulfilled and (2) from pending to rejected.

Promises are typically “read” by attaching callbacks to them. The most basic functions for that are Lwt.bind, which attaches a callback that is called when a promise becomes fulfilled, and Lwt.catch, for rejection.

Promise variables of this type, 'a Lwt.t, are actually read-only in Lwt. Separate resolvers of type 'a Lwt.u are used to write to them. Promises and their resolvers are created together by calling Lwt.wait. There is one exception to this: most promises can be canceled by calling Lwt.cancel, without going through a resolver.

Resolvers for promises of type 'a Lwt.t.

Each resolver can be thought of as the write end of one promise. It can be passed to Lwt.wakeup_later, Lwt.wakeup_later_exn, or Lwt.wakeup_later_result to resolve that promise.

Creates a new pending promise, paired with its resolver.

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 Lwt.bind.

However, it is important to understand Lwt.wait as the fundamental promise “constructor.” All other functions that evaluate to a promise can be, or are, eventually implemented in terms of it.

Lwt.wakeup_later r v fulfills, with value v, the pending promise associated with resolver r. This triggers callbacks attached to the promise.

If the promise is not pending, Lwt.wakeup_later raises Stdlib.Invalid_argument, unless the promise is canceled. If the promise is canceled, Lwt.wakeup_later has no effect.

If your program has multiple threads, it is important to make sure that Lwt.wakeup_later (and any similar function) is only called from the main thread. Lwt.wakeup_later 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 Lwt_preemptive or Lwt_unix.send_notification.

Lwt.wakeup_later_exn r exn is like Lwt.wakeup_later, except, if the associated promise is pending, it is rejected with exn.

Lwt.return v creates a new promise that is already fulfilled with value v.

This is needed to satisfy the type system in some cases. For example, in a match expression where one case evaluates to a promise, the other cases have to evaluate to promises as well:

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. *)

Another typical usage is in let%lwt. The expression after the “in” has to evaluate to a promise. So, if you compute an ordinary value instead, you have to wrap it:

let%lwt line = Lwt_io.(read_line stdin) in
Lwt.return (line ^ ".")

Lwt.fail exn is like Lwt.return, except the new promise that is already rejected with exn.

Whenever possible, it is recommended to use raise exn instead, as raise captures a backtrace, while Lwt.fail does not. If you call raise exn in a callback that is expected by Lwt to return a promise, Lwt will automatically wrap exn in a rejected promise, but the backtrace will have been recorded by the OCaml runtime.

For example, bind's second argument is a callback which returns a promise. And so it is recommended to use raise in the body of that callback. This applies to the aliases of bind as well: ( >>= ) and ( let* ).

Use Lwt.fail only when you specifically want to create a rejected promise, to pass to another function, or store in a data structure.

Lwt.bind p_1 f makes it so that f will run when p_1 is fulfilled.

When p_1 is fulfilled with value v_1, the callback f is called with that same value v_1. Eventually, after perhaps starting some I/O or other computation, f returns promise p_2.

Lwt.bind itself returns immediately. It only attaches the callback f to p_1 – it does not wait for p_2. What Lwt.bind returns is yet a third promise, p_3. Roughly speaking, fulfillment of p_3 represents both p_1 and p_2 becoming fulfilled, one after the other.

A minimal example of this is an echo program:

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 *)

Rejection of p_1 and p_2, and raising an exception in f, are all forwarded to rejection of p_3.

Precise behavior

Lwt.bind returns a promise p_3 immediately. p_3 starts out pending, and is resolved as follows:

• The first condition to wait for is that p_1 becomes resolved. It does not matter whether p_1 is already resolved when Lwt.bind is called, or becomes resolved later – the rest of the behavior is the same.
• If and when p_1 becomes resolved, it will, by definition, be either fulfilled or rejected.
• If p_1 is rejected, p_3 is rejected with the same exception.
• If p_1 is fulfilled, with value v, f is applied to v.
• f may finish by returning the promise p_2, or raising an exception.
• If f raises an exception, p_3 is rejected with that exception.
• Finally, the remaining case is when f returns p_2. From that point on, p_3 is effectively made into a reference to p_2. 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.

Syntactic sugar

Lwt.bind is almost never written directly, because sequences of Lwt.bind result in growing indentation and many parentheses:

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 *)

The recommended way to write Lwt.bind is using the let%lwt syntactic sugar:

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 *)

This uses the Lwt PPX (preprocessor). Note that we had to add package lwt_ppx to the command line for building this program. We will do that throughout this manual.

Another way to write Lwt.bind, that you may encounter while reading code, is with the >>= operator:

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 *)

The >>= operator comes from the module Lwt.Infix, which is why we opened it at the beginning of the program.

See also Lwt.map.

reraise e raises the exception e. Unlike raise e, reraise e preserves the existing exception backtrace and even adds a "Re-raised at" entry with the call location.

This function is intended to be used in the exception handlers of Lwt.catch and Lwt.try_bind.

It is also used in the code produced by Lwt_ppx.

Lwt.catch f h applies f (), which returns a promise, and then makes it so that h (“handler”) will run when that promise is rejected.

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 *)

Despite the above code, the recommended way to write Lwt.catch is using the try%lwt syntactic sugar from the PPX. Here is an equivalent example:

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 *)

A particular advantage of the PPX syntax is that it is not necessary to artificially insert a catch-all exn -> reraise exn case. Like in the core language's try expression, the catch-all case is implied in try%lwt.

Lwt.catch is a counterpart to Lwt.bind – Lwt.bind is for fulfillment, and Lwt.catch is for rejection.

As with Lwt.bind, three promises are involved:

• p_1, the promise returned from applying f ().
• p_2, the promise returned from applying h exn.
• p_3, the promise returned by Lwt.catch itself.

The remainder is (1) a precise description of how p_3 is resolved, and (2) a warning about accidentally using ordinary try for exception handling in asynchronous code.

(1) Lwt.catch first applies f (). It then returns p_3 immediately. p_3 starts out pending. It is resolved as follows:

• If f () returned a promise p_1, and p_1 becomes fulfilled, p_3 is fulfilled with the same value.
• p_1 can instead become rejected. There is one other possibility: f () itself raised an exception, instead of returning a promise. The behavior of Lwt.catch is the same whether f () raised an exception, or returned a promise that is later rejected with an exception. Let's call the exception exn.
• h exn is applied.
• h exn 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.
• If h exn raises another exception exn', p_3 is rejected with exn'.
• If h exn instead returns the promise p_2, p_3 is effectively made into a reference to p_2. This means p_3 and p_2 have the same state, undergo the same state changes, and performing any operation one is equivalent to performing it on the other.

Lwt.finalize f c applies f (), which returns a promise, and then makes it so c (“cleanup”) will run when that promise is resolved.

In other words, c runs no matter whether promise f () is fulfilled or rejected. As the names suggest, Lwt.finalize corresponds to the finally construct found in many programming languages, and c is typically used for cleaning up resources:

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 *)

As with Lwt.bind and Lwt.catch, there is a syntactic sugar for Lwt.finalize, though it is not as often used:

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 *)

Also as with Lwt.bind and Lwt.catch, three promises are involved:

• p_1, the promise returned from applying f ().
• p_2, the promise returned from applying c ().
• p_3, the promise returned by Lwt.finalize itself.

p_3 is returned immediately. It starts out pending, and is resolved as follows:

• f () is applied. If it finishes, it will either return a promise p_1, or raise an exception.
• If f () raises an exception, p_1 is created artificially as a promise rejected with that exception. So, no matter how f () finishes, there is a promise p_1 representing the outcome.
• After p_1 is resolved (fulfilled or rejected), c () is applied. This is meant to be the cleanup code.
• If c () finishes, it will also either return a promise, p_2, or raise an exception.
• If c () raises an exception, p_2 is created artificially as a promise rejected with that exception. Again, no matter how c () finishes, there is a promise p_2 representing the outcome of cleanup.
• If p_2 is fulfilled, p_3 is resolved the same way p_1 had been resolved. In other words, p_1 is forwarded to p_3 when cleanup is successful.
• If p_2 is rejected, p_3 is rejected with the same exception. In other words, p_2 is forwarded to p_3 when cleanup is unsuccessful. Note this means that if both the protected code and the cleanup fail, the cleanup exception has precedence.

Lwt.try_bind f g h applies f (), and then makes it so that:

• g will run when promise f () is fulfilled,
• h will run when promise f () is rejected.

Lwt.try_bind is a generalized Lwt.finalize. The difference is that Lwt.try_bind runs different callbacks depending on how f () is resolved. This has two main implications:

• The cleanup functions g and h each “know” whether f () was fulfilled or rejected.
• The cleanup functions g and h are passed the value f () was fulfilled with, and, respectively, the exception f () was rejected with.

As with Lwt.catch, it is recommended to use reraise in the catch-all case of the exception handler:

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 *)

The rest is a detailed description of the promises involved.

As with Lwt.finalize and the several preceding functions, three promises are involved.

• p_1 is the promise returned from applying f ().
• p_2 is the promise returned from applying h or g, depending on which one is chosen.
• p_3 is the promise returned by Lwt.try_bind itself.

Lwt.try_bind returns p_3 immediately. p_3 starts out pending, and is resolved as follows:

• f () is applied. If it finishes, it either returns p_1, or raises an exception.
• If f () raises an exception, p_1 is created artificially as a promise rejected with that exception. So, no matter how f () finishes, there is a promise p_1 representing the outcome.
• If p_1 is fulfilled, g is applied to the value p_1 is fulfilled with.
• If p_1 is rejected, h is applied to the exception p_1 is rejected with.
• 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.”
• If the callback finishes, it either returns p_2, or raises an exception.
• If the callback raises an exception, p_3 is rejected with that exception.
• If the callback returns p_2, p_3 is effectively made into an reference to p_2. They have the same state, including any state changes, and performing any operation on one is equivalent to performing it on the other.

Lwt.dont_wait f handler applies f (), which returns a promise, and then makes it so that if the promise is rejected, the exception is passed to handler.

In addition, if f () raises an exception, it is also passed to handler.

As the name implies, dont_wait (fun () -> <e>) handler is a way to evaluate the expression <e> (which typically has asynchronous side-effects) without waiting for the resolution of the promise <e> evaluates to.

dont_wait is meant as an alternative to async with a local, explicit, predictable exception handler.

Note that dont_wait f h causes f () to be evaluated immediately. Consequently, the non-yielding/non-pausing prefix of the body of f is evaluated immediately.

Lwt.async f applies f (), which returns a promise, and then makes it so that if the promise is rejected, the exception is passed to !Lwt.async_exception_hook.

In addition, if f () raises an exception, it is also passed to !Lwt.async_exception_hook.

!Lwt.async_exception_hook typically prints an error message and terminates the program. If you need a similar behaviour with a different exception handler, you can use Lwt.dont_wait.

Lwt.async is misleadingly named. Itself, it has nothing to do with asynchronous execution. It's actually a safety function for making Lwt programs more debuggable.

For example, take this program, which prints messages in a loop, while waiting for one line of user input:

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 *)

If one of the I/O operations in show_nag were to fail, the promise representing the whole loop would get rejected. However, since we are ignoring that promise at (1), 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.

A safer version differs only in using Lwt.async instead of Stdlib.ignore:

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 *)

In this version, if I/O in show_nag fails with an exception, the exception is printed by Lwt.async, and then the program exits.

The general rule for when to use Lwt.async is:

• Promises which are not passed to Lwt.bind, Lwt.catch, Lwt.join, etc., are top-level promises.
• One top-level promise is passed to Lwt_main.run, as can be seen in most examples in this manual.
• Every other top-level promise should be wrapped in Lwt.async.

Reference to a function, to be called on an "unhandled" exception.

This reference is used by Lwt.async, Lwt.on_cancel, Lwt.on_success, Lwt.on_failure, Lwt.on_termination, Lwt.on_any, Lwt_react.of_stream, and the deprecated Lwt.ignore_result.

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:

let () = Lwt.async (fun () -> raise Exit)

(* ocamlfind opt -linkpkg -package lwt code.ml && ./a.out *)

produces in the output:

Fatal error: exception Stdlib.Exit

If you are writing an application, you are welcome to reassign the reference, and replace the function with something more appropriate for your needs.

If you are writing a library, you should leave this reference alone. Its behavior should be determined by the application.

Lwt.both p_1 p_2 returns a promise that is pending until both promises p_1 and p_2 become resolved.

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 *)

If both p_1 and p_2 become fulfilled, Lwt.both p_1 p_2 is also fulfilled, with the pair of their final values. Otherwise, if at least one of the two promises becomes rejected, Lwt.both p_1 p_2 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.

• since 4.2.0

Lwt.join ps returns a promise that is pending until all promises in the list ps become resolved.

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 *)

If all of the promises in ps become fulfilled, Lwt.join ps is also fulfilled. Otherwise, if at least one promise in ps becomes rejected, Lwt.join ps 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.

Lwt.all ps is like Lwt.join ps: it waits for all promises in the list ps to become resolved.

It then resolves the returned promise with the list of all resulting values.

Note that if any of the promises in ps 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 ps were already resolved when one of them is rejected. For more fine-grained handling of rejection, structure the program with Lwt_stream or Lwt_list, handle rejections explicitly, or use Lwt.join and collect values manually.

• since 5.1.0

Lwt.pick ps returns a promise that is pending until one promise in the list ps becomes resolved.

When at least one promise in ps is resolved, Lwt.pick tries to cancel all other promises that are still pending, using Lwt.cancel.

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 *)

If the first promise in ps to become resolved is fulfilled, the result promise p is also fulfilled, with the same value. Likewise, if the first promise in ps to become resolved is rejected, p is rejected with the same exception.

If ps has no promises (if it is the empty list), Lwt.pick ps raises Stdlib.Invalid_argument _.

It's possible for multiple promises in ps to become resolved simultaneously. This happens most often when some promises ps are already resolved at the time Lwt.pick is called.

In that case, if at least one of the promises is rejected, the result promise p is rejected with the same exception as one such promise, chosen arbitrarily. If all promises are fulfilled, p is fulfilled with the value of one of the promises, also chosen arbitrarily.

The remaining functions in this section are variations on Lwt.pick.

Lwt.choose ps is the same as Lwt.pick ps, except that it does not try to cancel pending promises in ps.

Lwt.npick ps is similar to Lwt.pick ps, the difference being that when multiple promises in ps are fulfilled simultaneously (and none are rejected), the result promise is fulfilled with the list of values the promises were fulfilled with.

When at least one promise is rejected, Lwt.npick still rejects the result promise with the same exception.

Lwt.nchoose ps is the same as Lwt.npick ps, except that it does not try to cancel pending promises in ps.

Lwt.nchoose_split ps is the same as Lwt.nchoose ps, except that when multiple promises in ps are fulfilled simultaneously (and none are rejected), the result promise is fulfilled with both the list of values of the fulfilled promises, and the list of promises that are still pending.

Canceled promises are those rejected with this exception, Lwt.Canceled. See Lwt.cancel.

Lwt.task is the same as Lwt.wait, except the resulting promise p is cancelable.

This is significant, because it means promises created by Lwt.task can be resolved (specifically, rejected) by canceling them directly, in addition to being resolved through their paired resolvers.

In contrast, promises returned by Lwt.wait can only be resolved through their resolvers.

Lwt.cancel p attempts to cancel the pending promise p, without needing access to its resolver.

It is recommended to avoid Lwt.cancel, and handle cancelation by tracking the needed extra state explicitly within your library or application.

A canceled promise is one that has been rejected with exception Lwt.Canceled.

There are straightforward ways to make promises canceled. One could create a promise that starts out canceled, with Lwt.fail Lwt.Canceled. It's also possible to make a promise canceled through its resolver, by calling Lwt.wakeup_later_exn r Lwt.Canceled.

This function, Lwt.cancel, provides another method, which can cancel pending promises without going through their resolvers – it acts directly on promises.

Like any other promise rejection, the canceled state of a promise is propagated “forwards” by Lwt.bind, Lwt.join, etc., as described in the documentation of those functions.

Cancellation is a separate phase, triggered only by Lwt.cancel, that searches backwards, strating from p, for promises to reject with Lwt.Canceled. Once those promises are found, they are canceled, and then ordinary, forwards rejection propagation takes over.

All of this will be made precise, but first let's have an example:

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 *)

At the time Lwt.cancel is called, p “depends” on the sleep promise (the printl is not yet called, so its promise hasn't been created).

So, Lwt.cancel recursively tries to cancel the sleep promise. That is an example of the backwards search. The sleep promise is a pending promise that doesn't depend on anything, so backwards search stops at it. The state of the sleep promise is set to rejected with Lwt.Canceled.

Lwt.bind then propagates the rejection forwards to p, so p also becomes canceled.

Eventually, this rejection reaches Lwt_main.run, which raises the Lwt.Canceled as an ordinary exception. The sleep does not complete, and the printl is never started.

Promises, like the sleep promise above, that can be rejected by Lwt.cancel are cancelable. Most promises in Lwt are either cancelable, or depend on cancelable promises. The functions Lwt.wait and Lwt.no_cancel create promises that are not cancelable.

The rest is a detailed description of how the Lwt.cancel backwards search works.

• If p is already resolved, Lwt.cancel does nothing.
• If p was created by Lwt.wait or Lwt.no_cancel, Lwt.cancel does nothing.
• If p was created by Lwt.task or Lwt.protected, Lwt.cancel rejects it with Lwt.Canceled. This rejection then propagates normally through any Lwt calls that depend on p. Most I/O promises are internally created by calling Lwt.task.
• Suppose p_3 was returned by Lwt.bind, Lwt.map, Lwt.catch, Lwt.finalize, or Lwt.try_bind. Then, see those functions for the naming of the other promises involved. If p_3 is pending, then either p_1 is pending, or p_2 is pending. Lwt.cancel p_3 then tries recursively to cancel whichever of these two is still pending. If that succeeds, p_3 may be canceled later by the normal propagation of rejection.
• Suppose p was returned by Lwt.join, Lwt.pick, or similar function, which was applied to the promise list ps. Lwt.cancel then recursively tries to cancel each promise in ps. If one of those cancellations succeeds, p may be canceled later by the normal propagation of rejection.

Lwt.on_cancel p f makes it so that f will run when p becomes canceled.

Callbacks scheduled with on_cancel are guaranteed to run before any other callbacks that are triggered by rejection, such as those added by Lwt.catch.

Note that this does not interact directly with the cancellation mechanism, the backwards search described in Lwt.cancel. For example, manually rejecting a promise with Lwt.Canceled is sufficient to trigger f.

f should not raise exceptions. If it does, they are passed to !Lwt.async_exception_hook, which terminates the process by default.

Lwt.protected p creates a cancelable promise p'. The original state of p' is the same as the state of p at the time of the call.

The state of p' can change in one of two ways: a. if p changes state (i.e., is resolved), then p' eventually changes state to match p's, and b. during cancellation, if the backwards search described in Lwt.cancel reaches p' then it changes state to rejected Canceled and the search stops.

As a consequence of the b. case, Lwt.cancel (protected p) does not cancel p.

The promise p can still be canceled either directly (through Lwt.cancel p) or being reached by the backwards cancellation search via another path. Lwt.protected only prevents cancellation of p through p'.

Lwt.no_cancel p creates a non-cancelable promise p'. The original state of p' is the same as p at the time of the call.

If the state of p changes, then the state of p' eventually changes too to match p's.

Note that even though p' is non-cancelable, it can still become canceled if p is canceled. Lwt.no_cancel only prevents cancellation of p and p' through p'.

Lwt.wrap_in_cancelable p creates a cancelable promise p'. The original state of p' is the same as p.

The state of p' can change in one of two ways: a. if p changes state (i.e., is resolved), then p' eventually changes state to match p's, and b. during cancellation, if the backwards search described in Lwt.cancel reaches p' then it changes state to rejected Canceled and the search continues to p.

Lwt.map f p_1 is similar to Lwt.bind p_1 f, but f is not expected to return a promise.

This function is more convenient than Lwt.bind when f inherently does not return a promise. An example is Stdlib.int_of_string:

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 *)

By comparison, the Lwt.bind version is more awkward:

let read_int : unit -> int Lwt.t = fun () ->
  Lwt.bind
    Lwt_io.(read_line stdin)
    (fun line -> Lwt.return (int_of_string line))

As with Lwt.bind, sequences of calls to Lwt.map result in excessive indentation and parentheses. The recommended syntactic sugar for avoiding this is the >|= operator, which comes from module Lwt.Infix:

open Lwt.Infix

let read_int : unit -> int Lwt.t = fun () ->
  Lwt_io.(read_line stdin) >|= int_of_string

The detailed operation follows. For consistency with the promises in Lwt.bind, the two promises involved are named p_1 and p_3:

• p_1 is the promise passed to Lwt.map.
• p_3 is the promise returned by Lwt.map.

Lwt.map returns a promise p_3. p_3 starts out pending. It is resolved as follows:

• p_1 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.
• When p_1 becomes rejected, p_3 is rejected with the same exception.
• When p_1 instead becomes fulfilled, call the value it is fulfilled with v.
• f v is applied. If this finishes, it may either return another value, or raise an exception.
• If f v returns another value v', p_3 is fulfilled with v'.
• If f v raises exception exn, p_3 is rejected with exn.

Lwt.on_success p f makes it so that f will run when p is fulfilled.

It is similar to Lwt.bind, except no new promises are created. f is a plain, arbitrary function attached to p, to perform some side effect.

If f raises an exception, it is passed to !Lwt.async_exception_hook. By default, this will terminate the process.

Lwt.on_failure p f makes it so that f will run when p is rejected.

It is similar to Lwt.catch, except no new promises are created.

If f raises an exception, it is passed to !Lwt.async_exception_hook. By default, this will terminate the process.

Lwt.on_termination p f makes it so that f will run when p is resolved – that is, fulfilled or rejected.

It is similar to Lwt.finalize, except no new promises are created.

If f raises an exception, it is passed to !Lwt.async_exception_hook. By default, this will terminate the process.

Lwt.on_any p f g makes it so that:

• f will run when p is fulfilled,
• g will run when p is, alternatively, rejected.

It is similar to Lwt.try_bind, except no new promises are created.

If f or g raise an exception, the exception is passed to !Lwt.async_exception_hook. By default, this will terminate the process.

This module provides several infix operators for making programming with Lwt more convenient.

Lwt.return_unit is defined as Lwt.return (), but this definition is evaluated only once, during initialization of module Lwt, at the beginning of your program.

This means the promise is allocated only once. By contrast, each time Lwt.return () is evaluated, it allocates a new promise.

It is recommended to use Lwt.return_unit only where you know the allocations caused by an instance of Lwt.return () are a performance bottleneck. Generally, the cost of I/O tends to dominate the cost of Lwt.return () anyway.

In future Lwt, we hope to perform this optimization, of using a single, pre-allocated promise, automatically, wherever Lwt.return () is written.

Lwt.return_none is like Lwt.return_unit, but for Lwt.return None.

Lwt.return_nil is like Lwt.return_unit, but for Lwt.return [].

Lwt.return_true is like Lwt.return_unit, but for Lwt.return true.

Lwt.return_false is like Lwt.return_unit, but for Lwt.return false.

Counterpart to Lwt.return_none. However, unlike Lwt.return_none, this function performs no optimization. This is because it takes an argument, so it cannot be evaluated at initialization time, at which time the argument is not yet available.

Like Lwt.return_some, this function performs no optimization.

• since Lwt 2.6.0

Like Lwt.return_some, this function performs no optimization.

• since Lwt 2.6.0

Lwt.fail_with s is an abbreviation for

Lwt.fail (Stdlib.Failure s)

In most cases, it is better to use failwith s from the standard library. See Lwt.fail for an explanation.

Lwt.invalid_arg s is an abbreviation for

Lwt.fail (Stdlib.Invalid_argument s)

In most cases, it is better to use invalid_arg s from the standard library. See Lwt.fail for an explanation.

Lwt.of_result r converts an r to a resolved promise.

• If r is Ok v, Lwt.of_result r is Lwt.return v, i.e. a promise fulfilled with v.
• If r is Error exn, Lwt.of_result r is Lwt.fail exn, i.e. a promise rejected with exn.

Lwt.wakeup_later_result r result resolves the pending promise p associated to resolver r, according to result:

• If result is Ok v, p is fulfilled with v.
• If result is Error exn, p is rejected with exn.

If p is not pending, Lwt.wakeup_later_result raises Stdlib.Invalid_argument _, except if p is canceled. If p is canceled, Lwt.wakeup_later_result has no effect.

Lwt.state p evaluates to the current state of promise p:

• If p is fulfilled with value v, the result is Lwt.Return v.
• If p is rejected with exception exn, the result is Lwt.Fail exn.
• If p is pending, the result is Lwt.Sleep.

The constructor names are historical holdovers.

Keys into the implicit callback argument map, for implicit arguments of type 'a option.

The keys are abstract, but they are basically integers that are all distinct from each other.

See Lwt.with_value.

Creates a fresh implicit callback argument key.

The key is distinct from any other key created by the current process. The value None of type 'a option is immediately associated with the key.

See Lwt.with_value.

Retrieves the value currently associated with the given implicit callback argument key.

See Lwt.with_value.

Lwt.with_value k v f sets k to v in Lwt's internal implicit callback argument map, then runs f (), then restores the previous value associated with k.

Lwt maintains a single, global map, that can be used to “pass” extra arguments to callbacks:

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 *)

Note that the string Hello world! was passed to say_hello through the key k. Meanwhile, the only explicit argument of the callback say_hello is ().

The way this works is functions like Lwt.bind take a snapshot of the implicit argument map. Later, right before the callback is run, the map is restored 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.

To be more precise:

• Lwt.with_value associates Some "Hello world!" with k, and runs the function passed to it.
• This function contains the Lwt.bind.
• OCaml's eager evaluation means the arguments are evaluated first. In particular, the Lwt_unix.sleep 1. promise is created.
• Lwt.bind then attaches the callback in its second argument, the one which calls say_hello, to that sleep promise.
• Lwt.bind also takes a snapshot of the current state of the implicit argument map, and pairs the callback with that snapshot.
• The callback will not run for another second or so, when the sleep promise will be resolved.
• Instead, Lwt.bind returns its result promise p_3. This causes Lwt.with_value to also return p_3, first restoring k to be associated with None.
• Lwt_main.run gets the pending p_3, and blocks the whole process, with k associated with None.
• One second later, the sleep I/O completes, resolving the sleep promise.
• This triggers the say_hello callback. Right before the callback is called, the implicit argument map is restored to its snapshot, so k is associated with Some "Hello world!".
• After the callback completes, Lwt again restores k to be associated with None.

The Lwt functions that take snapshots of the implicit callback argument map are exactly those which attach callbacks to promises: Lwt.bind and its variants >>= and let%lwt, Lwt.map and its variant >|=, Lwt.catch and its variant try%lwt, Lwt.finalize and its variant %lwt.finally, Lwt.try_bind, Lwt.on_success, Lwt.on_failure, Lwt.on_termination, and Lwt.on_any.

Lwt.with_value should only be called in the main thread, i.e. do not call it inside Lwt_preemptive.detach.

Lwt.wakeup r v is like Lwt.wakeup_later r v, except it guarantees that callbacks associated with r will be called immediately, deeper on the current stack.

In contrast, Lwt.wakeup_later may 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.

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.

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 Lwt_mutex, Lwt_condition, and/or Lwt_mvar.

Lwt.wakeup_exn r exn is like Lwt.wakeup_later_exn r exn, but has the same problems as Lwt.wakeup.

Lwt.wakeup_result r result is like Lwt.wakeup_later_result r result, but has the same problems as Lwt.wakeup.

Lwt.add_task_r sequence is equivalent to

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

• deprecated

  Use of this function is discouraged for two reasons:

  • Lwt_sequence should not be used outside Lwt.
  • This function only exists because it performs a minor internal optimization, which may be removed.

Like Lwt.add_task_r, but the equivalent code calls Lwt_sequence.add_l instead.

• deprecated

  See add_task_r.

Lwt.pause () creates a pending promise that is fulfilled after Lwt finishes calling all currently ready callbacks, i.e. it is fulfilled on the next “tick.”

Putting the rest of your computation into a callback of Lwt.pause () creates a “yield” that gives other callbacks a chance to run first.

For example, to break up a long-running computation, allowing I/O to be handled between chunks:

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 *)

If you replace the call to Lwt.pause by Lwt.return in the program above, "Handling I/O" is printed only once. With Lwt.pause, it is printed several times, depending on the speed of your machine.

An alternative way to handle long-running computations is to detach them to preemptive threads using Lwt_preemptive.

Lwt.wrap f applies f (). If f () returns a value v, Lwt.wrap returns Lwt.return v. If f () raises an exception exn, Lwt.wrap returns Lwt.fail exn.

As a “prototype,” Lwt_wrap1 f creates a promise-valued function g:

let g v =
  try
    let v' = f v in
    Lwt.return v'
  with exn ->
    Lwt.fail exn

The remainder of the functions work analogously – they just work on f with larger numbers of arguments.

Note that there is an important difference to Lwt.wrap. These functions don't run f, nor create the final promise, immediately. In contrast, Lwt.wrap runs its argument f eagerly.

To get a suspended function instead of the eager execution of Lwt.wrap, use Lwt.wrap1.

Lwt.is_sleeping p is equivalent to Lwt.state p = Lwt.Sleep.

An obsolete variant of Lwt.async.

Lwt.ignore_result p behaves as follows:

• If p is already fulfilled, Lwt.ignore_result p does nothing.
• If p is already rejected with exn, Lwt.ignore_result p raises exn immediately.
• If p is pending, Lwt.ignore_result p does nothing, but if p becomes rejected later, the exception is passed to !Lwt.async_exception_hook.

Use of this function is discouraged for two reasons:

• The behavior is different depending on whether p is rejected now or later.
• The name is misleading, and has led to users thinking this function is analogous to Stdlib.ignore, i.e. that it waits for p to become resolved, completing any associated side effects along the way. In fact, the function that does that is ordinary Lwt.bind.