Garbage Collected C Libraries

0.25

[enable contents side-bar]

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:

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

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.

Generated 2009-11-23 for culibs-0.25 using Doxygen. Maintained by Petter Urkedal.