| 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 | `free' 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. |
| 72 | |
| 73 | * `sub.h' provides an allocation mechanism for small, |
| 74 | known-size blocks. It fetches big chunks from an underlying |
| 75 | allocator and divvies them up into small ones. This reduces |
| 76 | the overhead of calling the underlying allocator, and |
| 77 | (because the small blocks are linked together in lists by |
| 78 | their size) means that allocation and freeing are very |
| 79 | quick. It also reduces the amount of memory used by a small |
| 80 | amount. |
| 81 | |
| 82 | * `sym.h' provides a symbol table manager. It uses an |
| 83 | extensible hashing scheme (with 32-bit CRC as the hash |
| 84 | function), and permits arbitrary data blocks in both the |
| 85 | keys and values. It seems fairly quick. |
| 86 | |
| 87 | * `hash.h' provides the underpinnings of the `sym' hashtable. |
| 88 | It's a completely generic hashtable skeleton. It provides |
| 89 | the basics like rehashing when the table is full and so on. |
| 90 | It needs a fair bit of work to turn into a usable data |
| 91 | structure, though, which is what `sym' is for. |
| 92 | |
| 93 | * `dstr.h' provides a dynamically sized string type. In the |
| 94 | rather paltry tests I've run, it seemed faster than |
| 95 | libstdc++'s string type, but I shouldn't read too much into |
| 96 | that if I were you. The representation is exposed, in case |
| 97 | you want to start fiddling with it. Just make sure that the |
| 98 | string looks sane before you start expecting any of the |
| 99 | functions or macros to work. |
| 100 | |
| 101 | * `darray.h' implements dynamically growing arrays which can be |
| 102 | extended at both ends, a bit like Perl's. It replaces the |
| 103 | old `dynarray.h' which wasn't very good. However, `darray's |
| 104 | arrays are not sparse. Maybe a good sparse array module |
| 105 | will be added later. |
| 106 | |
| 107 | At the same conceptual level, there's some code for handling |
| 108 | multiplexed I/O. Although the core is named `sel', and it uses |
| 109 | `select' internally, it could fairly easily be changed to use |
| 110 | `poll' instead. |
| 111 | |
| 112 | * `tv.h' declares some useful arithmetic operations on the |
| 113 | `struct timeval' type used by the `select' system call. |
| 114 | |
| 115 | * `sel.h' declares a collection of types and routines for |
| 116 | handling `select' calls in a nice way. There's nothing |
| 117 | particularly exciting in itself, but it's a good base on |
| 118 | which to build other things. |
| 119 | |
| 120 | * `lbuf.h' accepts arbitrary chunks of data and then passes |
| 121 | completed text lines on to a function. This is handy when |
| 122 | you're trying to read text from a socket, but don't want to |
| 123 | block while the end of the line is on its way. (In |
| 124 | particular, that'd leave you vulnerable to a trivial denial- |
| 125 | of-service attack.) |
| 126 | |
| 127 | * `selbuf.h' implements an `lbuf' tied to a read selector. |
| 128 | Whenever completed lines are read from a particular source, |
| 129 | they're passed to a handler function. |
| 130 | |
| 131 | * `conn.h' handles non-blocking `connect'. It starts a |
| 132 | connect, and adds itself to the select system. When the |
| 133 | connect completes, you get given the file descriptor. |
| 134 | |
| 135 | * `ident.h' is an RFC931 (identd) client. |
| 136 | |
| 137 | * `bres.h' is a background name resolver. It keeps a pool of |
| 138 | resolver processes to answer queries. |
| 139 | |
| 140 | * `sig.h' traps signals and dispatches them through the |
| 141 | event-driven `sel' system. |
| 142 | |
| 143 | Then there's a bunch of other stuff. |
| 144 | |
| 145 | * `base64.h' does Base64 encoding and decoding. |
| 146 | |
| 147 | * `bits.h' provides some portable bit manipulation macros. |
| 148 | |
| 149 | * `crc32.h' declares the 32-bit CRC used by `sym'. |
| 150 | |
| 151 | * `env.h' provides some routines for handling environment |
| 152 | variables in a hashtable. |
| 153 | |
| 154 | * `fdflags.h' encapsulates some traditional little dances with |
| 155 | fcntl when playing with nonblocking files. |
| 156 | |
| 157 | * `lock.h' does fcntl-style locking with a timeout. |
| 158 | |
| 159 | * `quis.h' works out the program name from the value of |
| 160 | `argv[0]' and puts it in a variable for everything else to |
| 161 | find. |
| 162 | |
| 163 | * `report.h' reports fatal and nonfatal errors in the standard |
| 164 | Unixy way. |
| 165 | |
| 166 | * `str.h' provides some occasionally useful string- |
| 167 | manipulation toys. |
| 168 | |
| 169 | * `trace.h' provides a simple tracing facility, which can be |
| 170 | turned on and off both at compile- and run-time. |
| 171 | |
| 172 | * `testrig.h' is a generic test rig skeleton. It reads test |
| 173 | vector files with a slightly configurable syntax, passes the |
| 174 | arguments to a caller-defined test function, and reports the |
| 175 | results. It's particularly handy with cryptographic |
| 176 | algorithms, I find. |
| 177 | |
| 178 | * `url.h' does url-encoding, which armours mostly-textual |
| 179 | name/value pairs so they contain no whitespace characters. |
| 180 | |
| 181 | |
| 182 | Mark Wooding |
| 183 | mdw@nsict.org |
| 184 | \f |
| 185 | Local variables: |
| 186 | mode: text |
| 187 | End: |