From 4d20cbea4e73933410dcd06dc117f0a47e6790f4 Mon Sep 17 00:00:00 2001
From: Justin Ethier <justin.ethier@gmail.com>
Date: Tue, 25 Jun 2019 13:07:39 -0400
Subject: [PATCH] Updated docs for futures

---
 docs/api/cyclone/concurrent.md | 57 +++++++++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 7 deletions(-)

diff --git a/docs/api/cyclone/concurrent.md b/docs/api/cyclone/concurrent.md
index ec0cca6e..6e3b9fe5 100644
--- a/docs/api/cyclone/concurrent.md
+++ b/docs/api/cyclone/concurrent.md
@@ -13,14 +13,24 @@ This library complements the multithreading support provided by [SRFI 18](../srf
 [Immutability](#immutability)
 - [`immutable?`](#immutable)
 
+[Generic Concurrency](#generic-concurrency)
+- [`deref`](#deref)
+
 [Atoms](#atoms)
 - [`make-atom`](#make-atom)
 - [`atom`](#atom)
 - [`atom?`](#atom-1)
-- [`deref`](#deref)
 - [`swap!`](#swap)
 - [`compare-and-set!`](#compare-and-set)
 
+[Futures](#futures)
+- [`future?`](#future)
+- [`future`](#future-1)
+- [`future-call`](#future-call)
+- [`future-deref`](#future-deref)
+- [`future-done?`](#future-done)
+
+
 ## Shared Objects
 
 Cyclone allocates new objects using the current thread's local stack. This is efficient for single-threaded code but makes it difficult to use an object from another thread. An object on a local stack could be overwritten or moved at any time, leading to undefined behavior.  The solution is to guarantee an object is located in a section of memory available for use by any thread. We call these shared objects.
@@ -77,6 +87,14 @@ It is an error to call a mutation procedure (such as `set-car!` or `string-set!`
 
 Predicate that returns `#t` if `obj` is immutable and `#f` otherwise.
 
+## Generic Concurrency
+
+### deref
+
+    (deref object)
+
+Dereference; returns the current value of the given concurrency object.
+
 ## Atoms
 
 This section provides atomic operations. The API is modelled after Clojure's [Atoms](https://clojure.org/reference/atoms). Per the Clojure docs:
@@ -120,12 +138,6 @@ Create a new atom in the same manner as `make-atom`. If `obj` is not provided it
 
 Type predicate, returns `#t` if `obj` is an atom and `#f` otherwise.
 
-### deref
-
-    (deref atom)
-
-Dereference; returns the current value of `atom`. 
-
 ### swap!
 
     (swap! atom f . args)
@@ -144,3 +156,34 @@ Based on the procedure of the same name from Clojure.
 
 Atomically changes the value of `atom` to `newval` but only if the value of `atom` is currently equal to `oldval`. Based on the procedure of the same name from Clojure. This is also commonly known as the compare-and-swap (CAS) atomic instruction.
 
+## 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.
+
+### future?
+
+    (future? obj)
+
+Type predicate, returns `#t` if `obj` is a future and `#f` otherwise.
+
+### future
+
+*Syntax*
+
+    (future expr ...)
+
+Executes the given statements on another thread and returns a future object that can be dereferenced later to retrieve the cached result.
+
+### future-call
+
+    (future-call thunk)
+
+Invokes `thunk` on another thread and returns a future object that can be dereferenced later to retrieve the cached result.
+
+`thunk` is a function that takes no arguments.
+
+### future-done?
+
+    (future-done? obj)
+
+Returns `#t` if the future has finished executing on another thread, and `#f` otherwise.