Major API reorganization, test infrastructure

The API is now hidden behind functions. The GC struct can have an
unstable layout without affecting any compiled binaries (users of
Universal Service or collectors hidden behind the API). The
collectors can be called directly if desired.

The API now allows for different allocation flags. These will be
used in future extensions (like weak pointers). For now none are
used.

Tests are compiled for each collector. I can't think of a good
solution that will encompass everything I want to write, but for
now this will work on POSIX systems.

1 files changed, 53 insertions, 3 deletions

diff --git a/README.rst b/README.rst
index 404805e..ba606a6 100644
--- a/README.rst
+++ b/README.rst
@@ -2,7 +2,56 @@
 Universal Service
 =================
 
-Universal Service is a collection of garbage collectors written in C.
+Universal Service is a collection of garbage collectors written in C,
+designed to allow flexibility in programs that use it. All collectors
+are accessed using a common API so code written for one collector can be
+used with other collectors with the same feature set without modification.
+
+-----------
+Terminology
+-----------
+
+Generally speaking, ``UNS_WORD`` must be an integer that can be converted
+to and from a pointer to data. ``UNS_SWORD`` is the signed version of
+``UNS_WORD``. Both must be integer types.
+
+In collectors where this conversion cannot be assumed (like C89 collectors)
+or not possible, then ``UNS_WORD`` should be a type that can be used to
+index any arrays (like ``size_t``) and ``UNS_SWORD`` is like ``ssize_t``.
+
+A "region" denotes a block of memory in the heap. The "header" of a
+region is a hidden area of the region that holds information about
+the region.  It may not be connected to the actual region itself. A
+"pointer to a region" is a pointer to the first byte of user accessable
+space: it is not a pointer to the header.
+
+----------
+Collectors
+----------
+
+* ``cheney_c89``: A pure C89 copying collector. Useful for applications
+  that want a resizable heap.
+* (Planned) ``inplace_c89``: A pure C89 mark-lazy-sweep collector with
+  support for weak references.
+
+-----------------
+Adding Collectors
+-----------------
+
+The minimum set of functions a collector must define are
+
+* ``init``: Initialize ``Uns_GC`` with the heap and callbacks specific to
+  that collector.
+* ``collect``: Force a garbage collection.
+* ``alloc``: Allocate memory. All allocators must support at least
+  ``UNS_BYTES`` and ``UNS_RECORD``. All other type combinations are
+  optional. ``UNS_RECORD`` may be equivalent to a type combination
+  containing ``UNS_RECORD``.
+* ``deinit``: Free heap.
+* ``record_set``: Set an entry in a record to the passed value.
+  This function is not allowed to cause a garbage collection.
+* ``record_get``: Get the value of an entry.
+  This function is not allowed to cause a garbage collection.
 
 -------
 License
@@ -19,7 +68,8 @@ redistribute modifications to the LGPL code. From the
 > Does the LGPL have different requirements for statically vs dynamically
 > linked modules with a covered work?
 >
-> For the purpose of complying with the LGPL (any extant version: v2, v2.1 or v3):
+> For the purpose of complying with the LGPL (any extant version: v2,
+> v2.1 or v3):
 >
 > If you statically link against an LGPLed library, you must also
 > provide your application in an object (not necessarily source) format,
@@ -27,7 +77,7 @@ redistribute modifications to the LGPL code. From the
 > the application.
 
 You can statically link any LGPL 3.0 code to code of permissive licenses
-(like MIT), and even to source-available license (like the SSPL or the
+(like MIT), and even to source-available licenses (like the SSPL or the
 Commons Clause) as long as the end user can recompile the program to use
 their own version of the library.