chiark - git - mdw - mLib/blob - README

   1 mLib
   2
   3
   4 Overview
   5
   6         mLib is a collection of bits of code I've found handy in various
   7         programs.  With a few very minor exceptions, the routines are
   8         highly portable, and mostly strictly conformant.
   9
  10         My programming style is probably what you'd describe as
  11         `unconventional'.  I'm skeptical about object-orientation, and
  12         not a huge fan of over-hiding information of any kind.  The
  13         structure and interface of the library reflects these views.
  14
  15         There is now a (hopefully fairly good) set of manual pages for
  16         mLib.  The manual isn't installed by default since it takes a
  17         while to install and it's not a very good idea when it's part
  18         of a larger package.  To install the manual pages, say
  19
  20                 make install-man
  21
  22         (after everything else is built, obviously).
  23
  24
  25 Quick tour
  26
  27         mLib doesn't have much of a `structure' as such.  It's more a
  28         collection of useful things than a coherent whole.  Even so,
  29         it's possible to detect a vague layering of the library's
  30         components.
  31
  32         The underpinnings of the system are the exception structure, and
  33         the memory allocation routines.
  34
  35           * `exc.h' declares some macros which do a reasonable (though
  36             not perfect) job of providing exception handling facilities
  37             for C.
  38
  39           * `alloc.h' declares some thin veneers over `malloc' and
  40             `free' which raise exceptions for out-of-memory conditions,
  41             so you don't have to bother trapping these in main code.
  42
  43         Above this are the memory tracking system, the suballocator, and
  44         a couple of useful data structures.
  45
  46           * `track.h' declares the symbols required for a (very) simple
  47             memory allocation tracker.  I wrote it because I had a
  48             memory leak in a program.  It tags allocated memory blocks
  49             with information about who allocated them, and keeps track
  50             of the memory allocated so far.  Most of the time, you don't
  51             bother compiling this in, and you don't need to care about
  52             it at all.
  53
  54           * `sub.h' provides an allocation mechanism for small,
  55             known-size blocks.  It fetches big chunks from an underlying
  56             allocator and divvies them up into small ones.  This reduces
  57             the overhead of calling the underlying allocator, and
  58             (because the small blocks are linked together in lists by
  59             their size) means that allocation and freeing are very
  60             quick.  It also reduces the amount of memory used by a small
  61             amount.
  62
  63           * `sym.h' provides a symbol table manager.  It uses an
  64             extensible hashing scheme (with 32-bit CRC as the hash
  65             function), and permits arbitrary data blocks in both the
  66             keys and values.  It seems fairly quick.
  67
  68           * `dstr.h' provides a dynamically sized string type.  In the
  69             rather paltry tests I've run, it seemed faster than
  70             libstdc++'s string type, but I shouldn't read too much into
  71             that if I were you.  The representation is exposed, in case
  72             you want to start fiddling with it.  Just make sure that the
  73             string looks sane before you start expecting any of the
  74             functions or macros to work.
  75
  76           * `dynarray.h' is a big nasty macro which defines functions
  77             capable of dealing with dynamically-sized arrays of
  78             arbitrary types.  (You build a new set of functions for each
  79             type.  Think of it as a hacky C++ template-a-like.)  The
  80             arrays are sparse, but not ever-so efficient in terms of
  81             look-up time.
  82
  83         At the same conceptual level, there's some code for handling
  84         multiplexed I/O.  Although the core is named `sel', and it uses
  85         `select' internally, it could fairly easily be changed to use
  86         `poll' instead.
  87
  88           * `tv.h' declares some useful arithmetic operations on the
  89             `struct timeval' type used by the `select' system call.
  90
  91           * `sel.h' declares a collection of types and routines for
  92             handling `select' calls in a nice way.  There's nothing
  93             particularly exciting in itself, but it's a good base on
  94             which to build other things.
  95
  96           * `lbuf.h' accepts arbitrary chunks of data and then passes
  97             completed text lines on to a function.  This is handy when
  98             you're trying to read text from a socket, but don't want to
  99             block while the end of the line is on its way.  (In
 100             particular, that'd leave you vulnerable to a trivial denial-
 101             of-service attack.)
 102
 103           * `selbuf.h' implements an `lbuf' tied to a read selector.
 104             Whenever completed lines are read from a particular source,
 105             they're passed to a handler function.
 106
 107           * `conn.h' handles non-blocking `connect'.  It starts a
 108             connect, and adds itself to the select system.  When the
 109             connect completes, you get given the file descriptor.
 110
 111         Then there's a bunch of other stuff.
 112
 113           * `crc32.h' declares the 32-bit CRC used by `sym'.
 114
 115           * `quis.h' works out the program name from the value of
 116             `argv[0]' and puts it in a variable for everything else to
 117             find.
 118
 119           * `report.h' reports fatal and nonfatal errors in the standard
 120             Unixy way.
 121
 122           * `trace.h' provides a simple tracing facility, which can be
 123             turned on and off both at compile- and run-time.
 124
 125           * `testrig.h' is a generic test rig skeleton.  It reads test
 126             vector files with a slightly configurable syntax, passes the
 127             arguments to a caller-defined test function, and reports the
 128             results.  It's particularly handy with cryptographic
 129             algorithms, I find.
 130
 131
 132 Future directions
 133
 134         I'm going to write some manual pages.  Promise.
 135
 136
 137                                                                 Mark Wooding
 138                                                                 mdw@nsict.org