Updated docs

docs/api/cyclone/concurrent.md

@@ -5,9 +5,11 @@ title: API
 
 # Concurrency Library
 
-The `(cyclone concurrent)` library makes it easier to write concurrent programs using Cyclone.
+The `(cyclone concurrent)` library makes it easier to write concurrent programs using Cyclone, complementing the lower-level multithreading support provided by [SRFI 18](../srfi/18).
 
-This library complements the multithreading support provided by [SRFI 18](../srfi/18).
+Much of the API is based on, or inspired by, similar constructs from Clojure.
+
+Shared Queues and Thread Pools are loosly based on API's from [Sagittarius Scheme](https://bitbucket.org/ktakashi/sagittarius-scheme/wiki/Home).
 
 ## Index
 
@@ -20,6 +22,7 @@ This library complements the multithreading support provided by [SRFI 18](../srf
 
 [General](#general)
 - [`deref`](#deref)
+- [`realized?`](#realized)
 
 [Atoms](#atoms)
 - [`make-atom`](#make-atom)
@@ -28,6 +31,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)
@@ -121,6 +134,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). 
@@ -142,8 +161,8 @@ For example:
 
 Example programs:
 
-- Summing numbers using atomic operations: [`sum-atomic.scm`](https://github.com/justinethier/cyclone/tree/master/examples/threading/sum-atomic.scm)
-- For comparison, summing numbers using locks: [`sum-mutex.scm`](https://github.com/justinethier/cyclone/tree/master/examples/threading/sum-mutex.scm)
+- Summing numbers using atomic operations: [`sum-atomic.scm`](../../../examples/threading/sum-atomic.scm)
+- For comparison, summing numbers using locks: [`sum-mutex.scm`](../../../examples/threading/sum-mutex.scm)
 
 ### make-atom
 
@@ -186,6 +205,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 stores code that will not be executed until dereferenced via `deref`. The result is then cached.
+
+Delays are based on delay objects from Clojure. 
+
+Note delays are referred to as `shared-delay` 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 blocks 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` to differentiate them from the single-threaded 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.