| 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 | |
| 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 |
| 20 | your breath. |
| 21 | |
| 22 | |
| 23 | Quick tour |
| 24 | |
| 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 |
| 28 | components. |
| 29 | |
| 30 | The underpinnings of the system are the exception structure, and |
| 31 | the memory allocation routines. |
| 32 | |
| 33 | * `exc.h' declares some macros which do a reasonable (though |
| 34 | not perfect) job of providing exception handling facilities |
| 35 | for C. |
| 36 | |
| 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. |
| 40 | |
| 41 | Above this are the memory tracking system, the suballocator, and |
| 42 | a couple of useful data structures. |
| 43 | |
| 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 |
| 50 | it at all. |
| 51 | |
| 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 |
| 59 | amount. |
| 60 | |
| 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. |
| 65 | |
| 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. |
| 73 | |
| 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 |
| 79 | look-up time. |
| 80 | |
| 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 |
| 84 | `poll' instead. |
| 85 | |
| 86 | * `tv.h' declares some useful arithmetic operations on the |
| 87 | `struct timeval' type used by the `select' system call. |
| 88 | |
| 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. |
| 93 | |
| 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- |
| 99 | of-service attack.) |
| 100 | |
| 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. |
| 104 | |
| 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. |
| 108 | |
| 109 | Then there's a bunch of other stuff. |
| 110 | |
| 111 | * `crc32.h' declares the 32-bit CRC used by `sym'. |
| 112 | |
| 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 |
| 115 | find. |
| 116 | |
| 117 | * `report.h' reports fatal and nonfatal errors in the standard |
| 118 | Unixy way. |
| 119 | |
| 120 | * `trace.h' provides a simple tracing facility, which can be |
| 121 | turned on and off both at compile- and run-time. |
| 122 | |
| 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 |
| 127 | algorithms, I find. |
| 128 | |
| 129 | |
| 130 | Future directions |
| 131 | |
| 132 | I'm going to write some manual pages. Promise. |
| 133 | |
| 134 | |
| 135 | Mark Wooding |
| 136 | mdw@nsict.org |