fix: in Lock, prevent flambda from reordering mutex-protected operations

inspired by Mutex.protect in the stdlib, which is also `[@inline never]`
for this reason

src/core/fifo_pool.mli

@@ -29,10 +29,8 @@ val create : (unit -> t, _) create_args
 (** [create ()] makes a new thread pool.
     @param on_init_thread
       called at the beginning of each new thread in the pool.
-    @param min
+    @param num_threads
-      minimum size of the pool. See {!Pool.create_args}. The default is
+      number of worker threads. See {!Ws_pool.create} for more details.
-      [Domain.recommended_domain_count()], ie one worker per CPU core. On OCaml
-      4 the default is [4] (since there is only one domain).
     @param on_exit_thread called at the end of each worker thread in the pool.
     @param name name for the pool, used in tracing (since 0.6) *)
 

src/core/lock.ml

@@ -5,13 +5,13 @@ type 'a t = {
 
 let create content : _ t = { mutex = Mutex.create (); content }
 
-let with_ (self : _ t) f =
+let[@inline never] with_ (self : _ t) f =
   Mutex.lock self.mutex;
-  try
+  match f self.content with
-    let x = f self.content in
+  | x ->
     Mutex.unlock self.mutex;
     x
-  with e ->
+  | exception e ->
     Mutex.unlock self.mutex;
     raise e
 
@@ -24,13 +24,13 @@ let[@inline] update_map l f =
       l.content <- x';
       y)
 
-let get l =
+let[@inline never] get l =
   Mutex.lock l.mutex;
   let x = l.content in
   Mutex.unlock l.mutex;
   x
 
-let set l x =
+let[@inline never] set l x =
   Mutex.lock l.mutex;
   l.content <- x;
   Mutex.unlock l.mutex

src/core/ws_pool.mli

@@ -1,8 +1,8 @@
 (** Work-stealing thread pool.
 
     A pool of threads with a worker-stealing scheduler. The pool contains a
-    fixed number of threads that wait for work items to come, process these, and
+    fixed number of worker threads that wait for work items to come, process
-    loop.
+    these, and loop.
 
     This is good for CPU-intensive tasks that feature a lot of small tasks. Note
     that tasks will not always be processed in the order they are scheduled, so
@@ -15,8 +15,8 @@
     in it to stop (after they finish their work), and wait for them to stop.
 
     The threads are distributed across a fixed domain pool (whose size is
-    determined by {!Domain.recommended_domain_count} on OCaml 5, and simply the
+    determined by {!Domain.recommended_domain_count}. See {!create} for more
-    single runtime on OCaml 4). *)
+    details. *)
 
 include module type of Runner
 
@@ -36,8 +36,14 @@ val create : (unit -> t, _) create_args
     @param num_threads
       size of the pool, ie. number of worker threads. It will be at least [1]
       internally, so [0] or negative values make no sense. The default is
-      [Domain.recommended_domain_count()], ie one worker thread per CPU core. On
+      [Domain.recommended_domain_count()], ie one worker thread per CPU core.
-      OCaml 4 the default is [4] (since there is only one domain).
+
+    Note that specifying [num_threads=n] means that the degree of parallelism is
+    at most [n]. This behavior is different than the one of [Domainslib], see
+    https://github.com/c-cube/moonpool/issues/41 for context.
+
+    If you want to use all cores, use [Domain.recommended_domain_count()].
+
     @param on_exit_thread called at the end of each thread in the pool
     @param name
       a name for this thread pool, used if tracing is enabled (since 0.6) *)