14 .TH sub 3 "8 May 1999" mLib
16 sub \- efficient allocation and freeing of small blocks
26 .B "#include <mLib/sub.h>"
28 .B "void sub_init(void);"
29 .BI "void *sub_alloc(size_t " sz );
30 .BI "void sub_free(void *" p ", size_t " sz );
32 .BI "void *CREATE(" type );
33 .BI "void DESTROY(" type " *" p );
38 collection of functions and macros implement an efficient allocator for
39 small blocks of known sizes. Free blocks of the same size are linked
40 together in list, making freeing and allocation fast. The `free'
41 operation requires the block size as an argument, so there's no data
42 overhead for an allocated block. The system takes advantage of this by
43 allocating big chunks from the underlying system (actually via
45 q.v.) and splitting the chunks into smaller blocks of the right size, so
46 the space and time overhead from the underlying allocator is divided
53 bytes. If there isn't enough memory to allocate the block, the
60 function frees a block allocated by
62 You must know the size of the block in advance. Note that
64 never gives memory back to the underlying allocator. Free sub-blocks
65 are just made available to later calls of
68 Don't try to pass blocks allocated by
72 similarly, don't try to pass blocks allocated by
78 If you do, you'll get what you deserve.
84 are intended to provide a slightly more natural interface to
87 mystruct *p = sub_alloc(sizeof(mystruct));
91 mystruct p = CREATE(mystruct);
93 Similarly, the block can be freed by saying
97 rather than the more cumbersome
99 sub_free(p, sizeof(*p));
103 must be called before any of the other
111 Mark Wooding, <mdw@nsict.org>