chiark / gitweb /
Test universal hashing and fix bugs.
[mLib] / 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.  Once upon a time, almost all of the code was nearly-
8         strictly conforming C.  Since then, a big pile of Unix-specific
9         code's been added, with a particularly strong networking
10         emphasis.  The Unix-specific code is targetted at sensible
11         POSIX-conforming systems, and should port easily.
12
13         My programming style is probably what you'd describe as
14         `unconventional'.  I'm skeptical about object-orientation, and
15         not a huge fan of over-hiding information of any kind.  The
16         structure and interface of the library reflects these views.  On
17         the other hand, I like documentation quite a lot.
18
19
20 Documentation
21
22         There is now a (hopefully fairly good) set of manual pages for
23         mLib.  The manual isn't installed by default since it takes a
24         while to install and it's not a very good idea when it's part
25         of a larger package.  To install the manual pages, say
26
27                 make install-man
28
29         (after everything else is built, obviously).
30
31         There's also documentation in the header files.  The header file
32         comments were, in general, written at the same time as the code.
33         This has the disadvantage that they focus at a fairly low level,
34         and use terminology relating to the implementation rather than
35         the interface.
36
37         The header file comments can be handy for quick browsing.
38         However, the manual pages are considered the authoritative
39         source of information about the programming interface.  If you
40         have to look at the source code, it usually means that my
41         documentation or interface design is wrong.
42
43
44 Quick tour
45
46         mLib doesn't have much of a `structure' as such.  It's more a
47         collection of useful things than a coherent whole.  Even so,
48         it's possible to detect a vague layering of the library's
49         components.
50
51         The underpinnings of the system are the exception structure, and
52         the memory allocation routines.
53
54           * `exc.h' declares some macros which do a reasonable (though
55             not perfect) job of providing exception handling facilities
56             for C.
57
58           * `alloc.h' declares some thin veneers over `malloc' and
59             friends which raise exceptions for out-of-memory conditions,
60             so you don't have to bother trapping these in main code.
61
62         Above this are the memory tracking system, the suballocator, and
63         a couple of useful data structures.
64
65           * `track.h' declares the symbols required for a (very) simple
66             memory allocation tracker.  I wrote it because I had a
67             memory leak in a program.  It tags allocated memory blocks
68             with information about who allocated them, and keeps track
69             of the memory allocated so far.  Most of the time, you don't
70             bother compiling this in, and you don't need to care about
71             it at all.  [This may be withdrawn in a later release.  Too
72             much code in mLib doesn't support it properly, and it's not
73             being maintained or documented very well.]
74
75           * `sub.h' provides an allocation mechanism for small,
76             known-size blocks.  It fetches big chunks from an underlying
77             allocator and divvies them up into small ones.  This reduces
78             the overhead of calling the underlying allocator, and
79             (because the small blocks are linked together in lists by
80             their size) means that allocation and freeing are very
81             quick.  It also reduces the amount of memory used by a small
82             amount.
83
84           * `sym.h' provides a symbol table manager.  It uses an
85             extensible hashing scheme (with 32-bit CRC as the hash
86             function), and permits arbitrary data blocks in both the
87             keys and values.  It seems fairly quick.
88
89           * `hash.h' provides the underpinnings of the `sym' hashtable.
90             It's a completely generic hashtable skeleton.  It provides
91             the basics like rehashing when the table is full and so on.
92             It needs a fair bit of work to turn into a usable data
93             structure, though, which is what `sym' is for.
94
95           * `dstr.h' provides a dynamically sized string type.  In the
96             rather paltry tests I've run, it seemed faster than
97             libstdc++'s string type, but I shouldn't read too much into
98             that if I were you.  The representation is exposed, in case
99             you want to start fiddling with it.  Just make sure that the
100             string looks sane before you start expecting any of the
101             functions or macros to work.
102
103           * `darray.h' implements dynamically growing arrays which can be
104             extended at both ends, a bit like Perl's.  It replaces the
105             old `dynarray.h' which wasn't very good.  However, `darray's
106             arrays are not sparse.  Maybe a good sparse array module
107             will be added later.
108
109         At the same conceptual level, there's some code for handling
110         multiplexed I/O.  Although the core is named `sel', and it uses
111         `select' internally, it could fairly easily be changed to use
112         `poll' instead.
113
114           * `tv.h' declares some useful arithmetic operations on the
115             `struct timeval' type used by the `select' system call.
116
117           * `sel.h' declares a collection of types and routines for
118             handling `select' calls in a nice way.  There's nothing
119             particularly exciting in itself, but it's a good base on
120             which to build other things.
121
122           * `lbuf.h' accepts arbitrary chunks of data and then passes
123             completed text lines on to a function.  This is handy when
124             you're trying to read text from a socket, but don't want to
125             block while the end of the line is on its way.  (In
126             particular, that'd leave you vulnerable to a trivial denial-
127             of-service attack.)
128
129           * `selbuf.h' implements an `lbuf' tied to a read selector.
130             Whenever completed lines are read from a particular source,
131             they're passed to a handler function.
132
133           * `conn.h' handles non-blocking `connect'.  It starts a
134             connect, and adds itself to the select system.  When the
135             connect completes, you get given the file descriptor.
136
137           * `ident.h' is an RFC931 (identd) client.
138
139           * `bres.h' is a background name resolver.  It keeps a pool of
140             resolver processes to answer queries.
141
142           * `sig.h' traps signals and dispatches them through the
143             event-driven `sel' system.
144
145         Then there's a bunch of other stuff.
146
147           * `base64.h' does Base64 encoding and decoding.
148
149           * `bits.h' provides some portable bit manipulation macros.
150
151           * `crc32.h' declares the 32-bit CRC used by `sym'.
152
153           * `env.h' provides some routines for handling environment
154             variables in a hashtable.
155
156           * `fdflags.h' encapsulates some traditional little dances with
157             fcntl when playing with nonblocking files.
158
159           * `lock.h' does fcntl-style locking with a timeout.
160
161           * `quis.h' works out the program name from the value of
162             `argv[0]' and puts it in a variable for everything else to
163             find.
164
165           * `report.h' reports fatal and nonfatal errors in the standard
166             Unixy way.
167
168           * `str.h' provides some occasionally useful string-
169             manipulation toys.
170
171           * `trace.h' provides a simple tracing facility, which can be
172             turned on and off both at compile- and run-time.
173
174           * `testrig.h' is a generic test rig skeleton.  It reads test
175             vector files with a slightly configurable syntax, passes the
176             arguments to a caller-defined test function, and reports the
177             results.  It's particularly handy with cryptographic
178             algorithms, I find.
179
180           * `url.h' does url-encoding, which armours mostly-textual
181             name/value pairs so they contain no whitespace characters.
182
183
184                                                                 Mark Wooding
185                                                                 mdw@nsict.org
186 \f
187 Local variables:
188 mode: text
189 End: