some docs

Author: c-cube

src/direct/lwt_direct.mli

@@ -1,4 +1,39 @@
-(** Direct style control flow for Lwt. *)
+(** Direct style control flow for Lwt.
+
+    This module relies on OCaml 5's
+    {{:https://ocaml.org/manual/5.3/effects.html} effect handlers}.
+    Instead of chaining promises using {!Lwt.bind} and {!Lwt.map}
+    and other combinators, it becomes possible to start
+    lightweight "tasks" using [Lwt_direct.run (fun () -> ...)].
+    The body of such a task is written in direct-style code,
+    using OCaml's standard control flow structures such as loops,
+    higher-order functions, exception handlers, [match], etc.
+
+    Interactions with the rest of lwt can be done using [await],
+    for example:
+
+    {[
+    Lwt_direct.run (fun () ->
+      let continue = ref true in
+      while !continue do
+        match Lwt_io.read_line in_channel |> Lwt_direct.await with
+        | exception End_of_file -> continue := false
+        | line ->
+          let uppercase_line = String.uppercase_ascii line in
+          Lwt_io.write_line out_channel |> Lwt_direct.await
+      done)
+    ]}
+
+    This code snippet contains a simple "task" that repeatedly reads
+    a line from a [Lwt_io] channel, uppercases it, and writes the
+    uppercase version to another channel.
+
+    This task is itself a [unit Lwt.t], which is resolved when the function
+    returns. It is possible to use
+    {!Lwt_direct.run_in_the_background} to ignore the result and
+    let the task run in the background instead.
+
+    *)
 
 val run : (unit -> 'a) -> 'a Lwt.t
 (** [run f] runs the function [f ()] in a task within
@@ -31,5 +66,5 @@ val await : 'a Lwt.t -> 'a
     exception with which [prom] failed if it failed.
     If [prom] is not resolved yet, [await prom] will suspend the
     current task and resume it when [prom] is resolved.
-    calling [yield] outside of {!run} or {!run_in_the_background} will raise an exception,
+    calling [await] outside of {!run} or {!run_in_the_background} will raise an exception,
     crash your program, or otherwise cause errors. It is a programming error to do so. *)