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.
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.
15 Currently there's not a great deal in the way of documentation
16 for mLib. The header and source files are fairly verbosely
17 commented, though, and you shouldn't go far wrong if you just
18 read the function descriptions in the header. I'm working on a
19 proper set of manual pages for the whole thing, but don't hold
25 mLib doesn't have much of a `structure' as such. It's more a
26 collection of useful things than a coherent whole. Even so,
27 it's possible to detect a vague layering of the library's
30 The underpinnings of the system are the exception structure, and
31 the memory allocation routines.
33 * `exc.h' declares some macros which do a reasonable (though
34 not perfect) job of providing exception handling facilities
37 * `alloc.h' declares some thin veneers over `malloc' and
38 `free' which raise exceptions for out-of-memory conditions,
39 so you don't have to bother trapping these in main code.
41 Above this are the memory tracking system, the suballocator, and
42 a couple of useful data structures.
44 * `track.h' declares the symbols required for a (very) simple
45 memory allocation tracker. I wrote it because I had a
46 memory leak in a program. It tags allocated memory blocks
47 with information about who allocated them, and keeps track
48 of the memory allocated so far. Most of the time, you don't
49 bother compiling this in, and you don't need to care about
52 * `sub.h' provides an allocation mechanism for small,
53 known-size blocks. It fetches big chunks from an underlying
54 allocator and divvies them up into small ones. This reduces
55 the overhead of calling the underlying allocator, and
56 (because the small blocks are linked together in lists by
57 their size) means that allocation and freeing are very
58 quick. It also reduces the amount of memory used by a small
61 * `sym.h' provides a symbol table manager. It uses an
62 extensible hashing scheme (with 32-bit CRC as the hash
63 function), and permits arbitrary data blocks in both the
64 keys and values. It seems fairly quick.
66 * `dstr.h' provides a dynamically sized string type. In the
67 rather paltry tests I've run, it seemed faster than
68 libstdc++'s string type, but I shouldn't read too much into
69 that if I were you. The representation is exposed, in case
70 you want to start fiddling with it. Just make sure that the
71 string looks sane before you start expecting any of the
72 functions or macros to work.
74 * `dynarray.h' is a big nasty macro which defines functions
75 capable of dealing with dynamically-sized arrays of
76 arbitrary types. (You build a new set of functions for each
77 type. Think of it as a hacky C++ template-a-like.) The
78 arrays are sparse, but not ever-so efficient in terms of
81 At the same conceptual level, there's some code for handling
82 multiplexed I/O. Although the core is named `sel', and it uses
83 `select' internally, it could fairly easily be changed to use
86 * `tv.h' declares some useful arithmetic operations on the
87 `struct timeval' type used by the `select' system call.
89 * `sel.h' declares a collection of types and routines for
90 handling `select' calls in a nice way. There's nothing
91 particularly exciting in itself, but it's a good base on
92 which to build other things.
94 * `lbuf.h' accepts arbitrary chunks of data and then passes
95 completed text lines on to a function. This is handy when
96 you're trying to read text from a socket, but don't want to
97 block while the end of the line is on its way. (In
98 particular, that'd leave you vulnerable to a trivial denial-
101 * `selbuf.h' implements an `lbuf' tied to a read selector.
102 Whenever completed lines are read from a particular source,
103 they're passed to a handler function.
105 * `conn.h' handles non-blocking `connect'. It starts a
106 connect, and adds itself to the select system. When the
107 connect completes, you get given the file descriptor.
109 Then there's a bunch of other stuff.
111 * `crc32.h' declares the 32-bit CRC used by `sym'.
113 * `quis.h' works out the program name from the value of
114 `argv[0]' and puts it in a variable for everything else to
117 * `report.h' reports fatal and nonfatal errors in the standard
120 * `trace.h' provides a simple tracing facility, which can be
121 turned on and off both at compile- and run-time.
123 * `testrig.h' is a generic test rig skeleton. It reads test
124 vector files with a slightly configurable syntax, passes the
125 arguments to a caller-defined test function, and reports the
126 results. It's particularly handy with cryptographic
132 I'm going to write some manual pages. Promise.
~mdw / mLib / blob