Merge pull request ocsigen#905 from raphael-proust/raphael-p@small-do…

…cumentation-additions

small documentation additions

docs/Makefile

@@ -5,18 +5,21 @@ PKGS=\
 	-package bytes -package result \
 	-package bigarray -package unix \
 	-package ocaml-migrate-parsetree -package ppx_tools_versioned \
-	-package react
+	-package react \
+	-package domainslib
 
 INCS=\
 	-I ${BLD}/core/.lwt.objs/byte \
 	-I ${BLD}/ppx/.ppx_lwt.objs/byte \
 	-I ${BLD}/react/.lwt_react.objs/byte \
+	-I ${BLD}/domain/.lwt_domain.objs/byte \
 	-I ${BLD}/unix/.lwt_unix.objs/byte
 
 MLIS=\
 	$(wildcard ${SRC}/core/*.mli) \
 	$(wildcard ${SRC}/ppx/*.mli) \
 	$(wildcard ${SRC}/react/*.mli) \
+	$(wildcard ${SRC}/domain/*.mli) \
 	$(filter-out ${BLD}/unix/lwt_unix.cppo.mli,$(wildcard ${BLD}/unix/*.mli))
 
 MLIS := $(filter-out %.pp.mli,$(MLIS))

docs/apiref-intro

@@ -18,6 +18,7 @@ Lwt_pool
 Lwt_stream
 Lwt_switch
 Lwt_sequence
+Lwt_seq
 Lwt_pqueue
 }
 
@@ -70,6 +71,18 @@ Syntactic sugar for Lwt, such as [let%lwt x = e in e'] syntax for [bind].
 Ppx_lwt
 }
 
+{2 Multicore helpers}
+
+The {e lwt_domain} package provides helpers for executing some computations on
+different cores. It is an Lwt-specific abstraction over the {e domainslib}
+package.
+
+{!modules:
+Lwt_domain
+}
+
+This package depends on the {e core} library and the {e domainslib} package.
+
 {2 Miscellaneous}
 
 The following modules are wrapper for integration of non-Lwt

docs/manual.wiki

@@ -412,10 +412,10 @@ val p3 : '_a Lwt.t = <abstr>
 
 === {{{let*}}} syntax ===
 
-  To use Lwt with the {{{let*}}} syntax introduced in OCaml 4.08, you can define:
+  To use Lwt with the {{{let*}}} syntax introduced in OCaml 4.08, you can open
+  the {{{Syntax}}} module:
 
-<<code language="ocaml" |let (let*) = Lwt.bind
-let (and*) = Lwt.both
+<<code language="ocaml" |open Syntax
 >>
 
   Then, you can write
@@ -730,6 +730,30 @@ let () =
 
 == Other libraries ==
 
+=== Parallelise computations to other cores ===
+
+  If you have some compute-intensive steps within your program, you can execute
+  them on a separate core. You can get performance benefits from the
+  parallelisation. In addition, whilst your compute-intensive function is running
+  on a different core, your normal I/O-bound tasks continue running on the
+  original core.
+
+  The module {{{Lwt_domain}}} from the {{{lwt_domain}}} package provides all the
+  necessary helpers to achieve this. It is based on the {{{Domainslib}}} library
+  and uses similar concepts (such as tasks and pools).
+
+  First, you need to create a task pool:
+
+<<code language="ocaml" |val setup_pool : ?name:string -> int -> pool
+>>
+
+  Then you simple detach the function calls to the created pool:
+
+<<code language="ocaml" |val detach : pool -> ('a -> 'b) -> 'a -> 'b Lwt.t
+>>
+
+  The returned promise resolves as soon as the function returns.
+
 === Detaching computation to preemptive threads ===
 
   It may happen that you want to run a function which will take time to

src/core/lwt.mli

@@ -1795,7 +1795,9 @@ val make_value : 'a -> 'a result
     {{: https://ocaml.org/api/Stdlib.html#TYPEresult}
     [Ok v]} since OCaml 4.03. If you need compatibility with OCaml 4.02, use
     [Result.Ok] and depend on opam package
-    {{: https://opam.ocaml.org/packages/result/} [result]}. *)
+    {{: https://opam.ocaml.org/packages/result/} [result]}.
+
+    @deprecated Use [Result.Ok] instead *)
 
 val make_error : exn -> _ result
   [@@ocaml.deprecated
@@ -1804,7 +1806,9 @@ val make_error : exn -> _ result
     {{: https://ocaml.org/api/Stdlib.html#TYPEresult}
     [Error exn]} since OCaml 4.03. If you need compatibility with OCaml 4.02,
     use [Result.Error] and depend on opam package
-    {{: https://opam.ocaml.org/packages/result/} [result]}. *)
+    {{: https://opam.ocaml.org/packages/result/} [result]}.
+
+    @deprecated Use [Result.Error] instead. *)
 
 val waiter_of_wakener : 'a u -> 'a t
   [@@ocaml.deprecated
@@ -1814,8 +1818,7 @@ val waiter_of_wakener : 'a u -> 'a t
 (** [Lwt.waiter_of_wakener r] evaluates to the promise associated with resolver
     [r].
 
-    It is recommended to explicitly keep the reference to the promise
-    instead. *)
+    @deprecated Keep the reference to the promise instead. *)
 
 
 
@@ -1836,7 +1839,7 @@ Lwt.on_cancel p (fun () -> Lwt_sequence.remove node);
 p
 ]}
 
-    Use of this function is discouraged for two reasons:
+    @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
@@ -1847,7 +1850,9 @@ val add_task_l : ('a u) Lwt_sequence.t -> 'a t
 " Deprecated because Lwt_sequence is an implementation detail of Lwt. See
   https://github.com/ocsigen/lwt/issues/361"]
 (** Like {!Lwt.add_task_r}, but the equivalent code calls {!Lwt_sequence.add_l}
-    instead. *)
+    instead.
+
+    @deprecated See [add_task_r]. *)
 
 [@@@ocaml.warning "+3"]
 

src/unix/lwt_main.mli

@@ -47,9 +47,9 @@ val yield : unit -> unit Lwt.t [@@deprecated "Use Lwt.pause instead"]
       calling all currently ready callbacks, i.e. it is fulfilled on the next
       “tick.”
 
-      [yield] is now deprecated in favor of the more general {!Lwt.pause}
-      in order to avoid discrepancies in resolution (see below) and stay
-      compatible with other execution environments such as js_of_ocaml.
+      @deprecated Since 5.5.0 [yield] is deprecated in favor of the more general
+      {!Lwt.pause} in order to avoid discrepancies in resolution (see below) and
+      stay compatible with other execution environments such as js_of_ocaml.
 
       Currently, paused promises are resolved more frequently than yielded promises.
       The difference is unintended but existing applications could depend on it.

src/unix/lwt_unix.cppo.mli

@@ -53,9 +53,13 @@ val sleep : float -> unit Lwt.t
 
 val yield : unit -> unit Lwt.t [@@deprecated "Use Lwt.pause instead"]
   (** [yield ()] is a promise in a pending state. It resumes itself as soon as
-      possible and resolves with value [()]. *)
+      possible and resolves with value [()].
+
+      @deprecated Since 5.5.0 [yield] is deprecated. Use the more general
+      {!Lwt.pause} instead. See {!Lwt_main.yield} for additional details. *)
 
 val auto_yield : float -> (unit -> unit Lwt.t) [@@deprecated "Use Lwt_unix.auto_pause instead"]
+(** @deprecated Since 5.5.0. Use {!auto_pause} instead. *)
 
 val auto_pause : float -> (unit -> unit Lwt.t)
   (** [auto_pause timeout] returns a function [f], and [f ()] has the following
@@ -1295,8 +1299,8 @@ type async_method =
           This is the default. *)
   | Async_switch
     [@ocaml.deprecated " Use Lwt_unix.Async_detach."]
-      (** Currently a synonym for [Async_detach]. This was a different method in
-          the past. *)
+      (** @deprecated A synonym for [Async_detach]. This was a
+          different method in the past. *)
 
 val default_async_method : unit -> async_method
   [@@ocaml.deprecated
@@ -1589,14 +1593,17 @@ val has_wait4 : bool
 
 val somaxconn : unit -> int
   [@@ocaml.deprecated " This is an internal function."]
+  (** @deprecated This is for internal use only. *)
 
 val retained : 'a -> bool ref
   (** @deprecated Used for testing. *)
 
 val read_bigarray :
   string -> file_descr -> IO_vectors._bigarray -> int -> int -> int Lwt.t
   [@@ocaml.deprecated " This is an internal function."]
+  (** @deprecated This is for internal use only. *)
 
 val write_bigarray :
   string -> file_descr -> IO_vectors._bigarray -> int -> int -> int Lwt.t
   [@@ocaml.deprecated " This is an internal function."]
+  (** @deprecated This is for internal use only. *)