32a3ab99 |
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 | |
93f77e5b |
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). |
32a3ab99 |
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 |