Document atomic promises

Author: fare

doc/reference/gerbil/core/expression.md

@@ -169,8 +169,27 @@ macro.
 (delay expr)
 ```
 
-Creates a promise to evaluate `expr` when needed with the `force`
-primitive.  The value of the expression is memoized.
+Creates a promise to evaluate `expr` when needed with the `force` primitive.
+The value of the expression is memoized so it will only be evaluated once.
+
+Delay internally calls `make-promise` with a thunk that evaluates `expr`.
+Delay is efficient, but only safe in the simple case of evaluation in a single thread
+of expressions that succeed (i.e. no escaping continuations that later restart).
+Using it in the more complex case may cause incorrect or inconsistent behavior.
+To support more such complex cases (at a slight extra cost), see `delay-atomic`.
+
+## delay-atomic
+```
+(delay-atomic expr)
+```
+
+Creates a promise to evaluate `expr` when needed with the `force` primitive.
+The value of the expression is memoized so it will only be evaluated once.
+
+Delay-atomic internally calls `make-atomic-promise` with a thunk that evaluates `expr`.
+Delay-atomic is only slightly less efficient than `delay`, and is safe even in the case of
+concurrent evaluation in a multiple threads; it will also support failures and escapes from
+the thunk, and will issue an error if someone attempts to reenter such escaped thunks.
 
 ## do
 TODO

doc/reference/gerbil/runtime/control.md

@@ -0,0 +1,86 @@
+# Control Flow
+
+## make-promise
+```
+(make-promise thunk) -> promise
+
+  thunk := procedure taking no args
+```
+
+Creates a promise. You can access the result of the promise with `force`,
+which will compute the `thunk` the first time, memoize its result, and subsequently return it always.
+
+Note: The syntax `(delay expr)` creates a promise as if by `(make-promise (lambda () expr))`
+
+Beware: promises returned by `make-promise` are optimized for efficient use in a single-threaded context,
+and are not thread-safe, nor safe against escaping continuations that somehow reenter the thunk
+before it was fully computed. If you want safety in those cases, use `make-atomic-promise` below.
+
+## promise?
+``` scheme
+(promise? obj) -> boolean
+
+  obj := any object
+```
+
+Returns true if the object *obj* is a promise.
+
+## make-atomic-promise
+```
+(make-atomic-promise thunk) -> promise
+
+  thunk := procedure taking no args
+```
+
+Creates a promise that is safe in a single-threaded context.
+The promise can be fulfilled with the usual `force` primitive, same as with `make-promise`.
+
+It is safe for users in multiple threads to simultaneously try to force the promise:
+the first user will do the work, the other ones will wait for its result.
+The thunk of an atomic-promise will have only one instance running at once,
+and may complete only once, after which it will run no more and the result will be reused instead.
+In case of errors and retries from a caller,
+the partial side-effects of the incomplete thunk may happen
+more than once, so the thunk is responsible for appropriately protecting
+any data structure that may be affected, or for ensuring its partial effects are idempotent.
+
+If an error occurs while computing the thunk, or evaluation otherwise escapes from the thunk,
+the calling thread may catch the error or escaping value and process it;
+but it is an error that will be caught to then try to resume evaluation of the thunk
+from a continuation captured within it.
+Instead, the promise may be forced again by the same thread or another concurrent thread,
+that will hopefully evaluate the thunk to completion and return its result,
+or then again may in turn error out and escape.
+
+
+## call-with-parameters
+``` scheme
+(call-with-parameters thunk . parameterization) -> any
+
+  thunk := procedure taking no args
+
+parameterization:
+ parameter value ...
+```
+
+Calls *thunk* with parameterization.
+
+## with-catch
+``` scheme
+(with-catch handler thunk) -> any
+
+  handler, thunk := procedure
+```
+
+Calls *thunk* with *handler* as the exception catcher.
+
+## with-unwind-protect
+``` scheme
+(with-unwind-protect thunk fini) -> any
+
+  thunk, fini := procedure
+```
+
+Calls *thunk*, invoking *fini* when execution exits the dynamic extent
+of *thunk*.
+

src/gerbil/runtime/control.ss

@@ -12,21 +12,34 @@ namespace: #f
   => :promise
   (:- (##make-delay-promise thunk) :promise))
 
+;; A regular promise is not thread-safe, and there is a race condition in who will force the computation,
+;; wherein multiple threads might simultaneously do it, causing side-effects to happen multiple times,
+;; with different results, and the second to terminate to overwrite the first results.
+;; An atomic promise, by contrast, ensures that the thunk will be computed once and only once.
+;;
+;; This implementation offers the same API as a regular promise, with the same force primitive,
+;; oblivious that more work is done, at the cost of a bit extra overhead in this atomic case.
+;; If you care more about performance than about easy expression of safe computation,
+;; use lower-level primitives, or go deeper implement this functionality deeper into Gambit.
+;; Note that there is indeed a race condition for who will force the inner promise,
+;; but all racing workers except the first one will then wait for the mutex,
+;; grab the completed inner promise result, and idempotently all set the result of the outer promise
+;; to the same result of the inner promise, which is safe.
 (def (make-atomic-promise (thunk : :procedure))
   => :promise
-  (let ((mx (make-mutex 'promise))
-        (inner (make-promise thunk)))
-    (make-promise
+  (let ((inner (make-promise thunk)) ;; inner thread-unsafe promise
+        (mx (make-mutex 'promise))) ;; mutex ensuring only one worker may force the inner promise
+    (make-promise ;; outer promise allowing the usual force primitive to work
      (lambda ()
-       (let (once (vector 0))
-         (dynamic-wind
+       (let (once (vector 0)) ;; per-worker atomic marker that ensures there is no reentry in code
+         (dynamic-wind ;; ensure that escaping continuation may not cause reentry into the forcing frame
              (lambda ()
                (declare (not interrupts-enabled))
-               (unless (##fx= (##vector-cas! once 0 1 0) 0)
+               (unless (##fx= (##vector-cas! once 0 1 0) 0) ;; if you try hard to break atomicity, you lose
                  (error "Cannot reenter atomic block"))
-               (mutex-lock! mx))
+               (mutex-lock! mx)) ;; now get the mutex so you're the only one to compute the inner promise
              (cut ##force-out-of-line inner)
-             (cut mutex-unlock! mx)))))))
+             (cut mutex-unlock! mx))))))) ;; release the mutex
 
 (def* call-with-parameters
   (((thunk : :procedure)) (thunk))