From bcdb5a9c1b570904185074e1d939f41cf3188086 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Mon, 18 Jan 2016 19:15:11 -0500 Subject: [PATCH] Added a multithreaded section --- docs/User-Manual.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index 016a649c..f5e5ded1 100644 --- a/docs/User-Manual.md +++ b/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 [R7RS 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: