Several libraries of utility functions are distributed with the GAUL source code. These were written for rapid and easy development of portable C code. The provided routines are not developed along with GAUL, but packaged with it to facilitate easy distribution and installation. You are welcome to use these independently of GAUL. Many of them are routinely used in several projects, both GPL'd and proprietry. This shortfall is slowly being rectified. I apologise that these are not well documented, but they are generally very simple to use. These sets of functions include:

• linkedlist - Single-link and double-link list datastructures.
• avltree - Adel'son-Velskii and Landis tree (or, height-balanced 1-tree) datastructure.
• memory_util - Memory handling routines.
• random_util - Stateful-pseudo-random number generation routines.
• str_util - String handling and manipulation routines.
• dstr_util - Dynamic string handling and manipulation routines.
• log_util - Multithread/Multiprocessor-safe logging routines routines.
• mpi_util - Simple MPI-like wrappers around alternative parallel programming toolkits.
• table_util - Indexed data table routines.
• timer_util - Simple timer routines.
• compatibility - Compatibility functions.

List datastructure

Linked lists are very powerful, yet simple, container structures. Two versions are implemented.

• util/linkedlist.c
• util/linkedlist.h

Tree datastructure

Tree structures are discussed in all good programming textbooks. This is an efficient implementation of the AVL tree structure.

• util/avltree.c
• util/avltree.h

Memory handling

Flexible wrapper around the standard malloc() routines..

• util/memory_util.c
• util/memory_util.h
• util/memory_chunks.c
• util/memory_chunks.h

memory_util.c is intended as a general purpose, portable, memory tracking package that replaces the system calls realloc, calloc and realloc and free with "safer" routines while keeping track of all the memory currently allocated. Additional facilities to enable array overflow checks are included.

The neat thing about all this is that it can sit over the top of any other memory debugging library which replaces the standard malloc routines, transparently.

Has an easy-to-use memory chunk implementation. Chunks are created/destroyed using mem_chunk_new() and mem_chunk_destroy(). Individual atoms are created/destroyed using mem_chunk_alloc() and mem_chunk_free(). This may be disabled by defining MEMORY_NO_CHUNKS at compile time.

Compile the code with MEMORY_ALLOC_SAFE for simple wrappers around the standard system allocation memory routines. Compile with MEMORY_ALLOC_DEBUG for fully auditing wrappers. Compile with neither for the standard routines only. When MEMORY_ALLOC_DEBUG is defined or MEMORY_NO_CHUNKS is not defined, my AVL tree implementation is required.

FAQ:
Q. Why not just use Purify?
A. I can't afford it.
Q. Well, ElectricFence is free - so why not use that?
A. It is horrendously slow, and a huge memory hog.

Portable, Stateful, Pseudo-Random Number Generator

Routines for random number generation.

• util/random_util.c
• util/random_util.h

Portable routines for generating pseudo random numbers with the following features:

• Useful interface functions. (can specify ranges or specific distributions)
• System independant. (Generated numbers are reproducible across system types.)
• Enables saving and restoring state.
• SLang intrinsic function wrappers are provided (if the HAVE_SLANG constant is set to 1).

The algorithm used is the Mitchell and Moore variant of the standard additive number generator. The required array of numbers is populated by a using single seed value by using a linear congruential pseudo random number generator.

Usage:

• First call random_init().
• Call random_seed() to seed the PRNG (like srand()). Alternatively, random_tseed() to use system clock for seed.
• random_rand() is a rand() replacement, which is available for use but I would recommend the wrapper functions: random_int(), random_int_range() etc.
• random_get_state() and random_set_state() may be used to set, save, restore, and query the current state.

String functions

Anything must be an improvement over the standard C string API! (To be honest, this isn't really any improvement, but it is a bit more comprehensive.)

• util/str_util.c
• util/str_util.h

Dynamic string handling and manipulation

An alternative to null-terminated strings.

• util/dstr_util.c
• util/dstr_util.h

Log functions

Flexible log handling.

• util/log_util.c
• util/log_util.h

Message passing functions

Portability wrappers for MPI-like toolkits.

• util/mpi_util.c
• util/mpi_util.h

Indexed table datastructure

Simple indexed table implementation.

• util/table_util.c
• util/table_util.h

Timer functions

Simple timer routines. S-lang intrinsic function wrappers are provided.

• util/timer_util.c
• util/timer_util.h

Compatibility Functions

Functions and wrappers used as a result of porting efforts. These are required to overcome the problem of functions used being missing on alternative platforms.

• util/compatibility.c
• util/compatibility.h