GC with realtime support

doc/docs.txt

@@ -22,6 +22,10 @@ The documentation consists of several documents:
 - | `Manual <manual.html>`_
   | The Nimrod manual is a draft that will evolve into a proper specification.
 
+- | `GC <gc.html>`_
+  | Additional documentation about Nimrod's GC and how to operate it in a
+  | realtime setting.
+
 - | `Source code filters <filters.html>`_
   | The Nimrod compiler supports source code filters as a simple yet powerful
     builtin templating system.

doc/gc.txt

@@ -0,0 +1,58 @@
+==========================
+Nimrod's Garbage Collector
+==========================
+
+Introduction
+============
+
+This document describes how the GC works and how to tune it for (soft)
+realtime systems.
+
+The basic algorithm is *Deferrent Reference Counting* with cycle detection.
+References on the stack are not counted for better performance (and easier C
+code generation). The GC **never** scans the whole heap but it may scan the
+delta-subgraph of the heap that changed since its last run.
+
+
+The GC is only triggered in a memory allocation operation. It it not triggered
+by some timer or background thread.
+
+
+Realtime support
+================
+
+To enable realtime support, the switch `useRealtimeGC`:idx: needs to be
+defined. With this switch the GC supports the following operations:
+
+.. code-block:: nimrod
+  proc GC_setMaxPause*(MaxPauseInUs: int)
+  proc GC_step*(us: int, strongAdvice = false)
+
+After calling ``GC_setMaxPause`` any GC run tries to finish within 
+``MaxPauseInUs`` microseconds. XXX complete documentation
+
+
+
+Time measurement
+----------------
+
+The GC's way of measing time uses (see ``lib/system/timers.nim`` for the 
+implementation):
+
+1) ``QueryPerformanceCounter`` and ``QueryPerformanceFrequency`` on Windows.
+2) ``mach_absolute_time`` on Mac OS X.
+3) ``gettimeofday`` on Posix systems.
+
+As such it supports a resolution of nano seconds internally; however the API
+uses microseconds for convenience. 
+
+
+Define the symbol ``reportMissedDeadlines`` to make the GC output whenever it
+missed a deadline. The reporting will be enhances and supported by the API in
+later versions of the collector.
+
+
+Tweaking the GC
+===============
+
+To be written. 

doc/nimrodc.txt

@@ -142,6 +142,9 @@ Define               Effect
 ``useNimRtl``        Compile and link against ``nimrtl.dll``.
 ``useMalloc``        Makes Nimrod use C's `malloc`:idx: instead of Nimrod's 
                      own memory manager. This only works with ``gc:none``.
+``useRealtimeGC``    Enables support of Nimrod's GC for *soft* realtime 
+                     systems. See the documentation of the `gc <gc.html>`_ 
+                     for further information.
 ==================   =========================================================