From c51fb226ce0386baf16ac4c56f5809713f3f704a Mon Sep 17 00:00:00 2001
From: Justin Ethier <justin.ethier@gmail.com>
Date: Fri, 12 Jul 2019 13:31:57 -0400
Subject: [PATCH] Document new concurrency objects

---
 docs/api/cyclone/concurrent.md | 73 ++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/docs/api/cyclone/concurrent.md b/docs/api/cyclone/concurrent.md
index 6177b648..e8001afe 100644
--- a/docs/api/cyclone/concurrent.md
+++ b/docs/api/cyclone/concurrent.md
@@ -15,6 +15,7 @@ This library complements the multithreading support provided by [SRFI 18](../srf
 
 [General](#general)
 - [`deref`](#deref)
+- [`realized?`](#realized)
 
 [Atoms](#atoms)
 - [`make-atom`](#make-atom)
@@ -23,6 +24,16 @@ This library complements the multithreading support provided by [SRFI 18](../srf
 - [`swap!`](#swap)
 - [`compare-and-set!`](#compare-and-set)
 
+[Delays](#delays)
+- [`shared-delay?`](#shared-delay)
+- [`shared-delay`](#shared-delay-1)
+- [`make-shared-delay`](#make-shared-delay)
+
+[Promises](#promises)
+- [`shared-promise?`](#shared-promise)
+- [`make-shared-promise`](#make-shared-promise)
+- [`deliver`](#deliver)
+
 [Futures](#futures)
 - [`future?`](#future)
 - [`future`](#future-1)
@@ -116,6 +127,12 @@ Predicate that returns `#t` if `obj` is immutable and `#f` otherwise.
 
 Dereference; returns the current value of the given concurrency object.
 
+### realized?
+
+    (realized? obj)
+
+Returns `#t` if a value has been produced for a promise, delay, or future. Otherwise returns `#f`.
+
 ## Atoms
 
 This section provides atomic operations modelled after Clojure's [Atoms](https://clojure.org/reference/atoms). 
@@ -181,6 +198,62 @@ Atomically changes the value of `atom` to `newval` but only if the value of `ato
 
 Based on the procedure of the same name from Clojure. 
 
+## Delays
+
+A delay is created to execute code at a later time. When the result is required any thread can call `deref` to generate it. Once executed the result is cached so it is available for other threads.
+
+Delays are based on delay objects from Clojure. 
+
+Note delays are referred to as `shared-delay` in the code to differentiate them from the single-threaded `delay` provided by `(scheme lazy)`.
+
+### shared-delay?
+
+    (shared-delay? obj)
+
+Type predicate, returns `#t` if `obj` is a shared delay and `#f` otherwise.
+
+### shared-delay
+
+*Syntax*
+
+    (shared-delay body ...)
+
+Create a delay object that will execute `body` when dereferenced.
+
+### make-shared-delay
+
+    (make-shared-delay thunk)
+
+Create a delay object that will execute `thunk` when dereferenced.
+
+## Promises
+
+A promise allows one or more threads to wait for a value to be generated by another thread. When `deref` is called on a promise the calling thread will block until a value is delivered to the promise, via another thread calling `deliver`.
+
+Promises are based off of promise objects from Clojure.
+
+Note promises are referred to as `shared-promise` in the code to differentiate them from the single-threaded promise functionality provided by `(scheme lazy)`.
+
+###   shared-promise?
+
+    (shared-promise? obj)
+
+Type predicate, returns `#t` if `obj` is a shared promise and `#f` otherwise.
+
+### make-shared-promise
+
+    (make-shared-promise)
+
+Create a new promise object.
+
+### deliver
+
+    (deliver promise obj)
+
+Assign `promise` the value `obj` and unblock any threads that were waiting for the promise.
+
+Note that subsequent calls to `deliver` have no effect. A value may only be delivered once to a given promise.
+
 ## Futures
 
 Futures are used to perform computations on another thread. The results are cached and may be retrieved later using `deref`. Note that `deref` will block on a future until a result is generated by the other thread.