Merge pull request #1078 from yawaramin/doc-lwt-ppx-sequence

Add back documentation on sequencing PPX

Author: raphael-proust

README.md

@@ -8,7 +8,7 @@
 [github-actions-img]: https://github.com/ocsigen/lwt/actions/workflows/workflow.yml/badge.svg?branch=master
 
 Lwt is a concurrent programming library for OCaml. It provides a single data
-type: the *promise*, which is a value that will become determined in the future.
+type: the *promise*, which is a value that will become resolved in the future.
 Creating a promise spawns a computation. When that computation is I/O, Lwt runs
 it in parallel with your OCaml code.
 
@@ -20,9 +20,36 @@ Here is a simplistic Lwt program which requests the Google front page, and fails
 if the request is not completed in five seconds:
 
 ```ocaml
-open Lwt.Syntax
+let () =
+  let request =
+    let%lwt addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
+    let google = Lwt_unix.((List.hd addresses).ai_addr) in
+
+    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
+      write outgoing "GET / HTTP/1.1\r\n";%lwt
+      write outgoing "Connection: close\r\n\r\n";%lwt
+      let%lwt response = read incoming in
+      Lwt.return (Some response)))
+  in
+
+  let timeout =
+    Lwt_unix.sleep 5.;%lwt
+    Lwt.return_none
+  in
 
+  match Lwt_main.run (Lwt.pick [request; timeout]) with
+  | Some response -> print_string response
+  | None -> prerr_endline "Request timed out"; exit 1
+
+(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)
+```
+
+If you are not using the `lwt_ppx` syntax extension, you can use the `let*`
+binding opoerators from the `Lwt.Syntax` module instead.
+
+```ocaml
 let () =
+  let open Lwt.Syntax in
   let request =
     let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
     let google = Lwt_unix.((List.hd addresses).ai_addr) in
@@ -36,24 +63,29 @@ let () =
 
   let timeout =
     let* () = Lwt_unix.sleep 5. in
-    Lwt.return None
+    Lwt.return_none
   in
 
   match Lwt_main.run (Lwt.pick [request; timeout]) with
   | Some response -> print_string response
   | None -> prerr_endline "Request timed out"; exit 1
 
-(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)
+(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)
 ```
 
-In the program, functions such as `Lwt_io.write` create promises. The
-`let* ... in` construct is used to wait for a promise to become determined; the
-code after `in` is scheduled to run in a "callback." `Lwt.pick` races promises
-against each other, and behaves as the first one to complete. `Lwt_main.run`
-forces the whole promise-computation network to be executed. All the visible
-OCaml code is run in a single thread, but Lwt internally uses a combination of
-worker threads and non-blocking file descriptors to resolve in parallel the
-promises that do I/O.
+In the program above, functions such as `Lwt_io.write` create promises. The
+`let%lwt ... in` construct (provided by `lwt_ppx`) or the `let* ... in`
+construct (provided by `Lwt.Syntax`) are used to wait for a promise to resolve.
+The code after `in` is scheduled to run after the code inside the `let...in`
+has resolved.
+
+`Lwt.pick` races promises against each other, and behaves as the first one to
+complete.
+
+`Lwt_main.run` forces the whole promise-computation network to be executed. All
+the visible OCaml code is run in a single thread, but Lwt internally uses a
+combination of worker threads and non-blocking file descriptors to resolve in
+parallel the promises that do I/O.
 
 
 <br/>

src/core/index.mld

@@ -3,9 +3,9 @@
 {1 Introduction}
 
 Lwt is a concurrent programming library for OCaml. It provides a single data
-type: the {e promise}, which is a value that will become determined in the
-future. Creating a promise spawns a computation. When that computation is I/O,
-Lwt runs it in parallel with your OCaml code.
+type: the {e promise}, which is a value that will become resolved in the future.
+Creating a promise spawns a computation. When that computation is I/O, Lwt runs
+it in parallel with your OCaml code.
 
 OCaml code, including creating and waiting on promises, is run in a single
 thread by default, so you don't have to worry about locking or preemption. You
@@ -14,10 +14,37 @@ can detach code to be run in separate threads on an opt-in basis.
 Here is a simplistic Lwt program which requests the Google front page, and fails
 if the request is not completed in five seconds:
 
-{[
-open Lwt.Syntax
+{@ocaml[
+let () =
+  let request =
+    let%lwt addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
+    let google = Lwt_unix.((List.hd addresses).ai_addr) in
 
+    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
+      write outgoing "GET / HTTP/1.1\r\n";%lwt
+      write outgoing "Connection: close\r\n\r\n";%lwt
+      let%lwt response = read incoming in
+      Lwt.return (Some response)))
+  in
+
+  let timeout =
+    Lwt_unix.sleep 5.;%lwt
+    Lwt.return_none
+  in
+
+  match Lwt_main.run (Lwt.pick [request; timeout]) with
+  | Some response -> print_string response
+  | None -> prerr_endline "Request timed out"; exit 1
+
+(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)
+]}
+
+If you are not using the [lwt_ppx] syntax extension, you can use the [let*]
+binding opoerators from the [Lwt.Syntax] module instead.
+
+{@ocaml[
 let () =
+  let open Lwt.Syntax in
   let request =
     let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
     let google = Lwt_unix.((List.hd addresses).ai_addr) in
@@ -31,27 +58,30 @@ let () =
 
   let timeout =
     let* () = Lwt_unix.sleep 5. in
-    Lwt.return None
+    Lwt.return_none
   in
 
   match Lwt_main.run (Lwt.pick [request; timeout]) with
   | Some response -> print_string response
   | None -> prerr_endline "Request timed out"; exit 1
 
-(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)
+(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)
 ]}
 
-In the program, functions such as [Lwt_io.write] create promises. The
-[let%lwt ... in] construct is used to wait for a promise to become determined;
-the code after [in] is scheduled to run in a "callback." [Lwt.pick] races
-promises against each other, and behaves as the first one to complete.
+In the program above, functions such as [Lwt_io.write] create promises. The
+[let%lwt ... in] construct (provided by [lwt_ppx]) or the [let* ... in]
+construct (provided by [Lwt.Syntax]) are used to wait for a promise to resolve.
+The code after [in] is scheduled to run after the code inside the [let...in]
+has resolved.
+
+[Lwt.pick] races promises against each other, and behaves as the first one to
+complete.
+
 [Lwt_main.run] forces the whole promise-computation network to be executed. All
 the visible OCaml code is run in a single thread, but Lwt internally uses a
 combination of worker threads and non-blocking file descriptors to resolve in
 parallel the promises that do I/O.
 
-
-
 {1 Tour}
 
 Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's

src/core/lwt.mli

@@ -45,7 +45,7 @@
 let () =
   Lwt_main.run begin
     let%lwt data = Lwt_io.(read_line stdin) in
-    let%lwt () = Lwt_io.printl data in
+    Lwt_io.printl data;%lwt
     Lwt.return ()
   end
 
@@ -185,25 +185,26 @@ let () =
 {[
 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
+    let three_seconds : unit Lwt.t = Lwt_unix.sleep 3.
+    and five_seconds : unit Lwt.t = Lwt_unix.sleep 5. in
+
+    three_seconds;%lwt
+    Lwt_io.printl "3 seconds passed";%lwt
+    five_seconds;%lwt
     Lwt_io.printl "Only 2 more seconds passed"
   end
 
 (* ocamlfind opt -linkpkg -thread -package lwt_ppx,lwt.unix code.ml && ./a.out *)
 ]}
 
-    This program takes about five seconds to run. We are still new to [let%lwt],
-    so let's desugar it:
+    This program takes about five seconds to run. We are still new to [let%lwt]
+    and [;%lwt], so let's desugar them:
 
 {[
 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 three_seconds : unit Lwt.t = Lwt_unix.sleep 3.
+    and five_seconds : unit Lwt.t = Lwt_unix.sleep 5. in
 
     (* Both waits have already been started at this point! *)
 
@@ -542,7 +543,7 @@ let () =
 let () =
   Lwt_main.run begin
     let%lwt line = Lwt_io.(read_line stdin) in
-    let%lwt () = Lwt_unix.sleep 1. in
+    Lwt_unix.sleep 1.;%lwt
     Lwt_io.printf "One second ago, you entered %s\n" line
   end
 
@@ -834,8 +835,8 @@ val async : (unit -> unit t) -> unit
 {[
 let () =
   let rec show_nag () : _ Lwt.t =
-    let%lwt () = Lwt_io.printl "Please enter a line" in
-    let%lwt () = Lwt_unix.sleep 1. in
+    Lwt_io.printl "Please enter a line";%lwt
+    Lwt_unix.sleep 1.;%lwt
     show_nag ()
   in
   ignore (show_nag ());     (* Bad – see note for (1)! *)
@@ -860,8 +861,8 @@ let () =
 {[
 let () =
   let rec show_nag () : _ Lwt.t =
-    let%lwt () = Lwt_io.printl "Please enter a line" in
-    let%lwt () = Lwt_unix.sleep 1. in
+    Lwt_io.printl "Please enter a line";%lwt
+    Lwt_unix.sleep 1.;%lwt
     show_nag ()
   in
   Lwt.async (fun () -> show_nag ());
@@ -928,12 +929,12 @@ val both : 'a t -> 'b t -> ('a * 'b) t
 {[
 let () =
   let p_1 =
-    let%lwt () = Lwt_unix.sleep 3. in
+    Lwt_unix.sleep 3.;%lwt
     Lwt_io.printl "Three seconds elapsed"
   in
 
   let p_2 =
-    let%lwt () = Lwt_unix.sleep 5. in
+    Lwt_unix.sleep 5.;%lwt
     Lwt_io.printl "Five seconds elapsed"
   in
 
@@ -959,12 +960,12 @@ val join : (unit t) list -> unit t
 {[
 let () =
   let p_1 =
-    let%lwt () = Lwt_unix.sleep 3. in
+    Lwt_unix.sleep 3.;%lwt
     Lwt_io.printl "Three seconds elapsed"
   in
 
   let p_2 =
-    let%lwt () = Lwt_unix.sleep 5. in
+    Lwt_unix.sleep 5.;%lwt
     Lwt_io.printl "Five seconds elapsed"
   in
 
@@ -1120,7 +1121,7 @@ val cancel : _ t -> unit
 {[
 let () =
   let p =
-    let%lwt () = Lwt_unix.sleep 5. in
+    Lwt_unix.sleep 5.;%lwt
     Lwt_io.printl "Slept five seconds"
   in
 
@@ -1842,21 +1843,19 @@ val pause : unit -> unit t
 {[
 let () =
   let rec handle_io () =
-    let%lwt () = Lwt_io.printl "Handling I/O" in
-    let%lwt () = Lwt_unix.sleep 0.1 in
+    Lwt_io.printl "Handling I/O";%lwt
+    Lwt_unix.sleep 0.1;%lwt
     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
+      (if n mod 1_000_000 = 0 then
+        Lwt.pause ()
+      else
+        Lwt.return ());%lwt
       compute (n - 1)
   in