14 .TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
16 sub \- efficient allocation and freeing of small blocks
32 .B "#include <mLib/sub.h>"
34 .B "typedef struct { ...\& } subarena;"
36 .BI "void subarena_create(subarena *" s ", arena *" a );
37 .BI "void subarena_destroy(subarena *" s );
38 .BI "void subarena_alloc(subarena *" s ", size_t " sz );
39 .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
41 .B "void sub_init(void);"
42 .BI "void *sub_alloc(size_t " sz );
43 .BI "void sub_free(void *" p ", size_t " sz );
45 .BI "void *A_CREATE(subarena *" s ", " type );
46 .BI "void A_DESTROY(subarena *" s ", " type " *" p );
47 .BI "void *CREATE(" type );
48 .BI "void DESTROY(" type " *" p );
53 collection of functions and macros implement an efficient allocator for
54 small blocks of known sizes, constructed from a general allocator
57 Free blocks of the same size are linked together in list, making freeing
58 and allocation fast. The `free' operation requires the block size as an
59 argument, so there's no data overhead for an allocated block. The
60 system takes advantage of this by allocating big chunks from the
61 underlying arena and splitting the chunks into smaller blocks of the
62 right size, so the space and time overhead from the underlying allocator
63 is divided over many blocks.
69 bytes from the subarena
71 If there isn't enough memory to allocate the block, the
78 function frees a block allocated by
80 from the same subarena. You must know the size of the block in advance.
83 never gives memory back to the underlying allocator. Free sub-blocks
84 are just made available to later calls of
87 Don't try to free blocks allocated by
89 to the underlying arena's
91 function, or to try freeing blocks obtained directly from the arena's
95 If you do, you'll get what you deserve.
101 are intended to provide a slightly more natural interface to
104 mystruct *p = subarena_alloc(s, sizeof(mystruct));
108 mystruct p = A_CREATE(s, mystruct);
110 Similarly, the block can be freed by saying
114 rather than the more cumbersome
116 subarena_free(s, p, sizeof(*p));
118 There is a standard subarena
122 as its underlying allocator (obtained the first time the subarena is
135 ought to be called before any of the other functions as a matter of good
136 taste, but actually the system will initialize itself the first time
144 Mark Wooding, <mdw@distorted.org.uk>