--- /dev/null
+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.
+
+ Currently there's not a great deal in the way of documentation
+ for mLib. The header and source files are fairly verbosely
+ commented, though, and you shouldn't go far wrong if you just
+ read the function descriptions in the header. I'm working on a
+ proper set of manual pages for the whole thing, but don't hold
+ your breath.
+
+
+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
~mdw / mLib / blobdiff