Superceded by darray.

[mLib] / README

mLib


Overview

	mLib is a collection of bits of code I've found handy in various
	programs.  With a few very minor exceptions, the routines are
	highly portable, and mostly strictly conformant.

	My programming style is probably what you'd describe as
	`unconventional'.  I'm skeptical about object-orientation, and
	not a huge fan of over-hiding information of any kind.  The
	structure and interface of the library reflects these views.

	There is now a (hopefully fairly good) set of manual pages for
	mLib.  The manual isn't installed by default since it takes a
	while to install and it's not a very good idea when it's part
	of a larger package.  To install the manual pages, say

		make install-man

	(after everything else is built, obviously).


Quick tour

	mLib doesn't have much of a `structure' as such.  It's more a
	collection of useful things than a coherent whole.  Even so,
	it's possible to detect a vague layering of the library's
	components.

	The underpinnings of the system are the exception structure, and
	the memory allocation routines.

	  * `exc.h' declares some macros which do a reasonable (though
	    not perfect) job of providing exception handling facilities
	    for C.

	  * `alloc.h' declares some thin veneers over `malloc' and
	    `free' which raise exceptions for out-of-memory conditions,
	    so you don't have to bother trapping these in main code.

	Above this are the memory tracking system, the suballocator, and
	a couple of useful data structures.

	  * `track.h' declares the symbols required for a (very) simple
	    memory allocation tracker.  I wrote it because I had a
	    memory leak in a program.  It tags allocated memory blocks
	    with information about who allocated them, and keeps track
	    of the memory allocated so far.  Most of the time, you don't
	    bother compiling this in, and you don't need to care about
	    it at all.

	  * `sub.h' provides an allocation mechanism for small,
	    known-size blocks.  It fetches big chunks from an underlying
	    allocator and divvies them up into small ones.  This reduces
	    the overhead of calling the underlying allocator, and
	    (because the small blocks are linked together in lists by
	    their size) means that allocation and freeing are very
	    quick.  It also reduces the amount of memory used by a small
	    amount.

	  * `sym.h' provides a symbol table manager.  It uses an
	    extensible hashing scheme (with 32-bit CRC as the hash
	    function), and permits arbitrary data blocks in both the
	    keys and values.  It seems fairly quick.

	  * `dstr.h' provides a dynamically sized string type.  In the
	    rather paltry tests I've run, it seemed faster than
	    libstdc++'s string type, but I shouldn't read too much into
	    that if I were you.  The representation is exposed, in case
	    you want to start fiddling with it.  Just make sure that the
	    string looks sane before you start expecting any of the
	    functions or macros to work.

	  * `dynarray.h' is a big nasty macro which defines functions
	    capable of dealing with dynamically-sized arrays of
	    arbitrary types.  (You build a new set of functions for each
	    type.  Think of it as a hacky C++ template-a-like.)  The
	    arrays are sparse, but not ever-so efficient in terms of
	    look-up time.

	At the same conceptual level, there's some code for handling
	multiplexed I/O.  Although the core is named `sel', and it uses
	`select' internally, it could fairly easily be changed to use
	`poll' instead.

	  * `tv.h' declares some useful arithmetic operations on the
	    `struct timeval' type used by the `select' system call.

	  * `sel.h' declares a collection of types and routines for
	    handling `select' calls in a nice way.  There's nothing
	    particularly exciting in itself, but it's a good base on
	    which to build other things.

	  * `lbuf.h' accepts arbitrary chunks of data and then passes
	    completed text lines on to a function.  This is handy when
	    you're trying to read text from a socket, but don't want to
	    block while the end of the line is on its way.  (In
	    particular, that'd leave you vulnerable to a trivial denial-
	    of-service attack.)

	  * `selbuf.h' implements an `lbuf' tied to a read selector.
	    Whenever completed lines are read from a particular source,
	    they're passed to a handler function.

	  * `conn.h' handles non-blocking `connect'.  It starts a
	    connect, and adds itself to the select system.  When the
	    connect completes, you get given the file descriptor.

	Then there's a bunch of other stuff.

	  * `crc32.h' declares the 32-bit CRC used by `sym'.

	  * `quis.h' works out the program name from the value of
	    `argv[0]' and puts it in a variable for everything else to
	    find.

	  * `report.h' reports fatal and nonfatal errors in the standard
	    Unixy way.

	  * `trace.h' provides a simple tracing facility, which can be
	    turned on and off both at compile- and run-time.

	  * `testrig.h' is a generic test rig skeleton.  It reads test
	    vector files with a slightly configurable syntax, passes the
	    arguments to a caller-defined test function, and reports the
	    results.  It's particularly handy with cryptographic
	    algorithms, I find.


Future directions

	I'm going to write some manual pages.  Promise.


								Mark Wooding
								mdw@nsict.org