Garbage Collected C Libraries

0.25

Synopsis

This is a reference manual for the culibs, which is a set of libraries of basic (strings, containers) as well as more special-purpose (expressions) types and functions. A distinguishing feature is that all memory returned to the client is allocated with the Boehm-Demers-Weiser Conservative Garbage Collector.

The libraries are separated into modules, which are the basis for organising the documentation. So, a good starting point is the “Modules” section. You can completely ignore the “Data Structures” section, since all structure members are to be considered internal. Also, all identifiers which starts with cu*P_ are internal.

These libraries are licensed under the GNU General Public License, version 3 or later.

Why Garbage Collection?

General considerations on garbage collection for C are covered in Advantages and Disadvantages of Conservative Garbage Collection. Of particular interest here is it's application to the expression library. Expressions are big trees of small objects, and this is precisely the case where garbage collection excels. In addition it allows the use of hash-consing, which is used extensively in the expression library.

Status of Top-Level Modules

Most of these libraries is still to be considered a preview, since as they are subject to API changes. Roughly the status of various components are

component	status
cu: Common Infrastructure	mostly beta, somewhat unstable API
cucon: Containers	beta
cuos: Interface to the Operating System	beta
cutext: Unicode and Text Handling	alpha
cufo: Formatted Output	alpha
cuoo: Dynamic Objects and Operations	unstable API
cugra: A Small Graph Library	unstable API
cudyn: Dynamic Typing	deprecated, may be removed
cuex: Expressions	unstable API
cuflow: Control Flow	experimental

Requirements

The author has only tested these libraries on Linux systems. The aim is to support modern POSIX systems. In addition to the OS libraries, you need

library (components)	internal deps	external deps
`libcubase.la` (cu, cucon, cuoo)		libatomic_ops BDW-GC optional: libunwind
`libcuos.la` (cuos)	`libcubase.la`
`libcuflow.la` (cuflow)	`libcubase.la`	`librt.so` (system lib)
`libcugra.la` (cugra)	`libcubase.la`	optional: BuDDY
`libcuex.la` (cuex, cudyn)	`libcubase.la` `libcugra.la`	libffi

More information about the external libraries:

libatomic_ops comes bundled with gc-7.0, but if you install it in advance, gc will use the installed one.
The Boehm-Demers-Weiser Conservative Garbage Collector: If you intend to do any serious work with expressions (cuex and cudyn modules), consider recompiling the collector with the disclaim-patch mentioned under Download. This will significantly speed up hash-consing, but it is not strictly required.
libffi is part of GCC, but it is not installed by default. Check if your distribution has it, it will save you some work. Also, there is an older separate version which works on x86, but not on x86_64.

Compiling and Linking Against the Libraries

The libraries ship with a pkg-config specification for each module. So, if you use Autoconf, add

PKG_CHECK_MODULES(CULIBS, modules)

where modules is a list of the modules you want to use, and refer to $(CULIBS_CFLAGS) and $(CULIBS_LIBS) in your makefiles.

If you don't use Autoconf, you can obtain the flags to pass to the compiler with the pkg-config command, e.g.

gcc `pkg-config --cflags cu cucon cuos` -c test.c
gcc `pkg-config --libs cu cucon cuos` -o test test.o

Getting the Libraries

Download

In the download directory you will find

Source tarballs named culibs-*.tar.bz2
Patches to the garbage collector named bdwgc-rn-*.patch. This is not required, but recommended if you need good performance in the expression library.
- gc-DATE-disclaim-PATCHVERSION.patch applies to a CVS snapshot of the given date
- gc-VERSION-disclaim-PATCHVERSION.patch applies to GC releases.
- Comment on the patch.
If you don't find a patch that matches the GC version you want to use, try the closest before and after the date.

You can also browse or check out the Git sources at http://github.com/paurkedal/culibs.

Build and Install

After installing the above dependencies, unpack the source tarball, and from the top-level directory, type

./configure
make all install

If you only want to build the base libraries, replace the first command with

./configure --enable-modules=cu,cucon,cuos

This will excuse you from installing the extra requirements of the other components.