doc

src/core/fut.mli

@@ -204,7 +204,8 @@ val for_list : on:Runner.t -> 'a list -> ('a -> unit) -> unit t
 
 val await : 'a t -> 'a
 (** [await fut] suspends the current tasks until [fut] is fulfilled, then
-    resumes the task on this same runner.
+    resumes the task on this same runner (but possibly on a different
+    thread/domain).
 
     @since 0.3
 

src/core/lock.mli

@@ -1,5 +1,28 @@
 (** Mutex-protected resource.
 
+    This lock is a synchronous concurrency primitive, as a thin wrapper
+    around {!Mutex} that encourages proper management of the critical
+    section in RAII style:
+
+    {[
+      let (let@) = (@@)
+
+
+      …
+      let compute_foo =
+        (* enter critical section *)
+        let@ x = Lock.with_ protected_resource in
+        use_x;
+        return_foo ()
+        (* exit critical section *)
+      in
+      …
+    ]}
+
+    This lock does not work well with {!Fut.await}. A critical section
+    that contains a call to [await] might cause deadlocks, or lock starvation,
+    because it will hold onto the lock while it goes to sleep.
+
     @since 0.3 *)
 
 type 'a t