32a3ab99 |
1 | mLib |
2 | |
3 | |
4 | Overview |
5 | |
6 | mLib is a collection of bits of code I've found handy in various |
323ffb6c |
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. |
32a3ab99 |
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 |
323ffb6c |
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 |
32a3ab99 |
21 | |
93f77e5b |
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). |
32a3ab99 |
30 | |
323ffb6c |
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 | |
32a3ab99 |
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 |
e351a12d |
59 | friends which raise exceptions for out-of-memory conditions, |
32a3ab99 |
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 |
e351a12d |
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.] |
32a3ab99 |
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 | |
323ffb6c |
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 | |
32a3ab99 |
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 | |
323ffb6c |
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. |
32a3ab99 |
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 | |
323ffb6c |
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 | |
32a3ab99 |
145 | Then there's a bunch of other stuff. |
146 | |
9b64ede2 |
147 | * `base32.h' does Base32 encoding and decoding. This is a |
148 | mad thing one needs for sha1 URNs. |
149 | |
323ffb6c |
150 | * `base64.h' does Base64 encoding and decoding. |
151 | |
152 | * `bits.h' provides some portable bit manipulation macros. |
153 | |
32a3ab99 |
154 | * `crc32.h' declares the 32-bit CRC used by `sym'. |
155 | |
323ffb6c |
156 | * `env.h' provides some routines for handling environment |
157 | variables in a hashtable. |
158 | |
159 | * `fdflags.h' encapsulates some traditional little dances with |
160 | fcntl when playing with nonblocking files. |
161 | |
9b64ede2 |
162 | * `hex.h' does hex encoding and decoding. |
163 | |
323ffb6c |
164 | * `lock.h' does fcntl-style locking with a timeout. |
165 | |
32a3ab99 |
166 | * `quis.h' works out the program name from the value of |
167 | `argv[0]' and puts it in a variable for everything else to |
168 | find. |
169 | |
170 | * `report.h' reports fatal and nonfatal errors in the standard |
171 | Unixy way. |
172 | |
323ffb6c |
173 | * `str.h' provides some occasionally useful string- |
174 | manipulation toys. |
175 | |
32a3ab99 |
176 | * `trace.h' provides a simple tracing facility, which can be |
177 | turned on and off both at compile- and run-time. |
178 | |
179 | * `testrig.h' is a generic test rig skeleton. It reads test |
180 | vector files with a slightly configurable syntax, passes the |
181 | arguments to a caller-defined test function, and reports the |
182 | results. It's particularly handy with cryptographic |
183 | algorithms, I find. |
184 | |
9b64ede2 |
185 | * `unihash.h' provides universal hashing. This is useful in |
186 | hash tables for preventing uneven loading even in the |
187 | presence of a malicious person choosing the hash keys. |
188 | |
323ffb6c |
189 | * `url.h' does url-encoding, which armours mostly-textual |
190 | name/value pairs so they contain no whitespace characters. |
32a3ab99 |
191 | |
9b64ede2 |
192 | -- [mdw] |
32a3ab99 |
193 | |
323ffb6c |
194 | \f |
195 | Local variables: |
196 | mode: text |
197 | End: |