libstash(3s)

NAME
libstash - Library of algorithms and data structures designed for transaction processing.

SYNOPSIS

  Single-threaded
cc file -lstash
cc -g -D_LIBSTASH_DEBUG file -lstash_d
cc -pg file -lstash_p #include <libstash/libstash.h>

  Multi-threaded
cc file -lstash_r -lpthread
cc -g -D_LIBSTASH_DEBUG file -lstash_r_d -lpthread
cc -pg file -lstash_r_p -lpthread #include <libstash/libstash_r.h>

  General
cw_bool_t
libstash_init (void) void
libstash_shutdown (void)

  Preprocessor macros
void *
_cw_malloc (size_t a_size) void *
_cw_calloc (size_t a_number, size_t a_size) void *
_cw_realloc (void * a_ptr, size_t a_size) void *
_cw_free (void * a_ptr) void
_cw_assert (<expression>) void
_cw_check_ptr (void * a_ptr) void
_cw_marker (const char * a_str) void
_cw_error (const char * a_str) cw_uint64_t
_cw_ntohq (cw_uint64_t a_val) cw_uint64_t
_cw_htonq (cw_uint64_t a_val)

DESCRIPTION
The libstash library defines a number of algorithms and data structures that are useful for many purposes, but the library specifically targets the needs of transaction processing. The main artifact of this focus is that many classes use 64 bit variables in places where most applications would work fine with 32 bit variables. libstash is designed to run on *nix platforms, and is known to work on FreeBSD, Linux, and Solaris. The pthreads library is required for the multi-threaded versions of libstash.

USAGE
Detailed usage of the various available classes is discussed in detail in other man pages. Regardless of what classes are used, at least the following minimal shell of C code should be used.
    #include <libstash/libstash.h> int
    main()
    {
      libstash_init();
      /* Do stuff. */
      libstash_shutdown();
      return 0;
    }
Although nothing will fatally break if libstash_init() is not called, a number of things will work better. This is especially true of the debugging versions of the library, since a number of debugging aids are not active unless the library is initialized. cw_bool_t
libstash_init (void)
    Input(s):
        None.
    Output(s):
        retval:
            FALSE: Success.
            TRUE: Memory allocation error.
    Description:
        Initialize various global variables. In particular, initialize cw_g_mem, cw_g_dbg, cw_g_log, and cw_g_out.
void
libstash_shutdown (void)
    Input(s):
        None.
    Output(s):
        None.
    Description:
        Clean up the global variables that are initialized by libstash_init().
void *
_cw_malloc (size_t a_size)
    Input(s):
        a_size:
            Size of memory block desired.
    Output(s):
        retval:
            Pointer to a memory block, or NULL.
            NULL: Memory allocation error.
    Description:
        mem_malloc() wrapper. Return a pointer to a newly allocated block of memory of size i_size.
void *
_cw_calloc (size_t a_number, size_t a_size)
    Input(s):
        a_number:
            Number of elements.
        a_size:
            Size of each element.
    Output(s):
        retval:
            Pointer to a memory block, or NULL.
            NULL: Memory allocation error.
    Description:
        mem_calloc() wrapper. Return a pointer to a newly allocated array of a_number items, where each item is a_size bytes.
void *
_cw_realloc (void * a_ptr, size_t a_size)
    Input(s):
        a_ptr:
            Pointer to memory block to be reallocated.
        a_size:
            Size of memory block desired.
    Output(s):
        retval:
            Pointer to a memory block, or NULL.
            NULL: Memory allocation error.
    Description:
        mem_realloc() wrapper. Return a pointer to a block of memory with up to a_size bytes of a_ptr's data preserved. Use the space at a_ptr if possible.
void *
_cw_free (void * a_ptr)
    Input(s):
        a_ptr:
            Pointer to a memory block.
    Output(s):
        None.
    Description:
        mem_free() wrapper. Free the memory block pointed to by a_ptr.
void
_cw_assert (<expression>)
    Input(s):
        <expression>:
            A C language expression that evaluates to zero or non-zero.
    Output(s):
        Possible error message printed to cw_g_out.
    Description:
        If <expression> evaluates to zero, print an error message to cw_g_out and abort(). Note: This macro is optimized out of the non-debug versions of the library.
void
_cw_check_ptr (void * a_ptr)
    Input(s):
        a_ptr:
            Pointer.
    Output(s):
        Possible error message printed to cw_g_out.
    Description:
        if a_ptr is NULL, print an error message to cw_g_out and abort(). Note: This macro is optimized out of the non-debug versions of the library.
void
_cw_marker (const char * a_str)
    Input(s):
        a_str:
            Pointer to a NULL-terminated character array.
    Output(s):
        Contents of a_str printed to cw_g_out.
    Description:
        Print the contents of a_str to cw_g_out.
void
_cw_error (const char * a_str)
    Input(s):
        a_str:
            Pointer to a NULL-terminated character array.
    Output(s):
        Contents of a_str printed to cw_g_out.
    Description:
        Print the contents of a_str to cw_g_out.
cw_uint64_t
_cw_ntohq (cw_uint64_t a_val)
    Input(s):
        a_val:
            64 bit integer.
    Output(s):
        retval:
            64 bit integer.
    Description:
        Convert a_val from network byte order to host byte order and return the result.
cw_uint64_t
_cw_htonq (cw_uint64_t a_val)
    Input(s):
        a_val:
            64 bit integer.
    Output(s):
        retval:
            64 bit integer.
    Description:
        Convert a_val from host byte order to network byte order and return the result.
<return type>
<func> (<args>)
    Input(s):
        <input>:
            <input description>
    Output(s):
        retval:
            <retval description>
    Description:
        <description>

CODE STRUCTURE

  Object-oriented C
The algorithms and data structures in libstash are architected in an object-oriented manner, though all the actual code is C. Since C doesn't directly support object-oriented design, a number of stylistic conventions are used. Each class is referred to by a name, which is used as a prefix for all member methods. For example, open hashing is implemented by the oh class, and member methods of oh are named oh_new(), oh_delete(), oh_item_insert(), etc.

  Variable types
libstash is careful to use the following data types rather than the built-in types (other than when using system library functions and string pointers (char *)) to allow easy porting and explicit knowledge of variable sizes.
C data types
Type name | sizeof | Description
cw_bool_t | 4 | Boolean, either FALSE or TRUE.
cw_sint8_t | 1 | Signed 8 bit variable.
cw_uint8_t | 1 | Unsigned 8 bit variable.
cw_sint16_t | 2 | Signed 16 bit variable.
cw_uint16_t | 2 | Unsigned 16 bit variable.
cw_sint32_t | 4 | Signed 32 bit variable.
cw_uint32_t | 4 | Unsigned 32 bit variable.
cw_sint64_t | 8 | Signed 64 bit variable.
cw_uint64_t | 8 | Unsigned 64 bit variable.

  Object instantiation
Many classes provide a means for external memory allocation, and in some cases for automatic cleanup during destruction. This feature enables improved performance and cache locality, but if misunderstood, can result in mysterious memory corruption and leaks.

  Including headers
Rather than directly including header files, preprocessor macros are defined before including libstash.h. For example, to use the oh class, _LIBSTASH_USE_OH should be defined. The manpages for individual classes tell what preprocessor macros to define when using various classes.

  Variable naming
Though the variable naming conventions used in libstash are far short of what Hungarian and other naming conventions attempt, there are a few to take note of.
Variable prefixes
Prefix | Description
cw_g_ | Global variable.
a_ | Function argument.
t_ | Temporary variable.

SEE ALSO
Classes built into libstash
Name | Man page | Description
bhp | libstash_bhp(3s) | Binomial heap.
bhpi | libstash_bhp(3s) | Binomial heap node.
buf | libstash_buf(3s) | Extensible buffer.
bufc | libstash_buf(3s) | Reference-counted memory buffer.
cnd | libstash_thread(3s) | Condition.
dbg | libstash_dbg(3s) | Runtime debugging symbol lookup.
jtl | libstash_locks(3s) | JOE-tree lock.
list | libstash_list(3s) | Doubly linked list.
log | libstash_log(3s) | Logging (printf(3) wrapper).
matrix | libstash_matrix(3s) | Matrix.
mem | libstash_mem(3s) | Memory allocation (malloc(3) wrapper).
mq | libstash_mq(3s) | Message queue.
mtx | libstash_thread(3s) | Mutex.
oh | libstash_oh(3s) | Open hashing.
out | libstash_out(3s) | Output (printf(3) replacement).
pezz | libstash_pezz(3s) | Cached memory allocation.
res | libstash_res(3s) | Resource (name/value pairs).
ring | libstash_ring(3s) | Ring (similar uses as for lists).
rwl | libstash_locks(3s) | Read/write lock.
sem | libstash_thread(3s) | Semaphore.
thd | libstash_thread(3s) | Thread.
treen | libstash_treen(3s) | Arbitrary tree.
tsd | libstash_thread(3s) | Thread-specific data.

HISTORY
Written by Jason Evans <jasone@canonware.com>.