Added a multithreaded section

docs/User-Manual.md

@@ -12,6 +12,7 @@
   - [Generated Files](#generated-files)
   - [Interpreter](#interpreter)
 - [Language Details](#language-details)
+- [Multithreaded Programming](#multithreaded-programming)
 - [Foreign Function Interface](#foreign-function-interface)
 - [Licensing](#licensing)
 - [References and Further Reading](#references-and-further-reading)
@@ -123,6 +124,22 @@ A [R<sup>7</sup>RS Compliance Chart](Scheme-Language-Compliance.md) lists differ
 
 [API Documentation](API.md) is available for the libraries provide by Cyclone.
 
+# Multithreaded Programming
+
+The [`srfi 18`](api/srfi/18.md) library may be imported to provide support for multithreaded programs. See the [SRFI 18 specification](http://srfi.schemers.org/srfi-18/srfi-18.html) for more background information.
+
+Due to how Cyclone's garbage collector is implemented objects are relocated in memory when they are moved from the first generation (on the stack) to the second generation (on the heap). This causes problems when an object is used by multiple threads, as the address another thread expects to find an object at may suddenly change. To prevent this race condition an object must be guaranteed to be on the heap prior to being used by another thread. There are two ways to meet this guarantee:
+
+- Use the `->heap` function to place a copy of an object on the heap. Note this will only create a copy of a single object. A vector of objects would not have the contents of the vector moved, and a list would only have its immediate cons cell copied.
+
+- The `Cyc-minor-gc` function may be used to trigger a minor garbage collection for the executing thread. This is a more expensive operation than `->heap` but guarantees all objects on the thread's stack are copied to the heap.
+
+Finally, note there are some objects that are not relocated so the above does not apply:
+
+- Characters are stored using value types and do not need to be garbage collected.
+- Symbols are stored in a global table rather than the stack/heap.
+- Mutexes are always allocated on the heap since by definition they are used by more than one thread.
+
 # Foreign Function Interface
 
 The `define-c` special form can be used to define a function containing user-defined C code. This code will be carried through from the Scheme file all the way to the compiled C file. For example: