From: mdw Date: Fri, 14 May 1999 21:00:19 +0000 (+0000) Subject: Overview of the library. Unfortunately, this is in lieu of proper X-Git-Tag: 2.0.4~327 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/commitdiff_plain/32a3ab9914c04d2069dac2d01ecb28a6ac3b6d87 Overview of the library. Unfortunately, this is in lieu of proper manpages. --- diff --git a/README b/README new file mode 100644 index 0000000..0d0d8ad --- /dev/null +++ b/README @@ -0,0 +1,136 @@ +mLib + + +Overview + + mLib is a collection of bits of code I've found handy in various + programs. With a few very minor exceptions, the routines are + highly portable, and mostly strictly conformant. + + My programming style is probably what you'd describe as + `unconventional'. I'm skeptical about object-orientation, and + not a huge fan of over-hiding information of any kind. The + structure and interface of the library reflects these views. + + Currently there's not a great deal in the way of documentation + for mLib. The header and source files are fairly verbosely + commented, though, and you shouldn't go far wrong if you just + read the function descriptions in the header. I'm working on a + proper set of manual pages for the whole thing, but don't hold + your breath. + + +Quick tour + + mLib doesn't have much of a `structure' as such. It's more a + collection of useful things than a coherent whole. Even so, + it's possible to detect a vague layering of the library's + components. + + The underpinnings of the system are the exception structure, and + the memory allocation routines. + + * `exc.h' declares some macros which do a reasonable (though + not perfect) job of providing exception handling facilities + for C. + + * `alloc.h' declares some thin veneers over `malloc' and + `free' which raise exceptions for out-of-memory conditions, + so you don't have to bother trapping these in main code. + + Above this are the memory tracking system, the suballocator, and + a couple of useful data structures. + + * `track.h' declares the symbols required for a (very) simple + memory allocation tracker. I wrote it because I had a + memory leak in a program. It tags allocated memory blocks + with information about who allocated them, and keeps track + of the memory allocated so far. Most of the time, you don't + bother compiling this in, and you don't need to care about + it at all. + + * `sub.h' provides an allocation mechanism for small, + known-size blocks. It fetches big chunks from an underlying + allocator and divvies them up into small ones. This reduces + the overhead of calling the underlying allocator, and + (because the small blocks are linked together in lists by + their size) means that allocation and freeing are very + quick. It also reduces the amount of memory used by a small + amount. + + * `sym.h' provides a symbol table manager. It uses an + extensible hashing scheme (with 32-bit CRC as the hash + function), and permits arbitrary data blocks in both the + keys and values. It seems fairly quick. + + * `dstr.h' provides a dynamically sized string type. In the + rather paltry tests I've run, it seemed faster than + libstdc++'s string type, but I shouldn't read too much into + that if I were you. The representation is exposed, in case + you want to start fiddling with it. Just make sure that the + string looks sane before you start expecting any of the + functions or macros to work. + + * `dynarray.h' is a big nasty macro which defines functions + capable of dealing with dynamically-sized arrays of + arbitrary types. (You build a new set of functions for each + type. Think of it as a hacky C++ template-a-like.) The + arrays are sparse, but not ever-so efficient in terms of + look-up time. + + At the same conceptual level, there's some code for handling + multiplexed I/O. Although the core is named `sel', and it uses + `select' internally, it could fairly easily be changed to use + `poll' instead. + + * `tv.h' declares some useful arithmetic operations on the + `struct timeval' type used by the `select' system call. + + * `sel.h' declares a collection of types and routines for + handling `select' calls in a nice way. There's nothing + particularly exciting in itself, but it's a good base on + which to build other things. + + * `lbuf.h' accepts arbitrary chunks of data and then passes + completed text lines on to a function. This is handy when + you're trying to read text from a socket, but don't want to + block while the end of the line is on its way. (In + particular, that'd leave you vulnerable to a trivial denial- + of-service attack.) + + * `selbuf.h' implements an `lbuf' tied to a read selector. + Whenever completed lines are read from a particular source, + they're passed to a handler function. + + * `conn.h' handles non-blocking `connect'. It starts a + connect, and adds itself to the select system. When the + connect completes, you get given the file descriptor. + + Then there's a bunch of other stuff. + + * `crc32.h' declares the 32-bit CRC used by `sym'. + + * `quis.h' works out the program name from the value of + `argv[0]' and puts it in a variable for everything else to + find. + + * `report.h' reports fatal and nonfatal errors in the standard + Unixy way. + + * `trace.h' provides a simple tracing facility, which can be + turned on and off both at compile- and run-time. + + * `testrig.h' is a generic test rig skeleton. It reads test + vector files with a slightly configurable syntax, passes the + arguments to a caller-defined test function, and reports the + results. It's particularly handy with cryptographic + algorithms, I find. + + +Future directions + + I'm going to write some manual pages. Promise. + + + Mark Wooding + mdw@nsict.org