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 .BI "void subarena_create(subarena *" s ", arena *" a );
35 .BI "void subarena_destroy(subarena *" s );
36 .BI "void subarena_alloc(subarena *" s ", size_t " sz );
37 .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
39 .B "void sub_init(void);"
40 .BI "void *sub_alloc(size_t " sz );
41 .BI "void sub_free(void *" p ", size_t " sz );
43 .BI "void *A_CREATE(subarena *" s ", " type );
44 .BI "void A_DESTROY(subarena *" s ", " type " *" p );
45 .BI "void *CREATE(" type );
46 .BI "void DESTROY(" type " *" p );
51 collection of functions and macros implement an efficient allocator for
52 small blocks of known sizes, constructed from a general allocator
55 Free blocks of the same size are linked together in list, making freeing
56 and allocation fast. The `free' operation requires the block size as an
57 argument, so there's no data overhead for an allocated block. The
58 system takes advantage of this by allocating big chunks from the
59 underlying arena and splitting the chunks into smaller blocks of the
60 right size, so the space and time overhead from the underlying allocator
61 is divided over many blocks.
67 bytes from the subarena
69 If there isn't enough memory to allocate the block, the
76 function frees a block allocated by
78 from the same subarena. You must know the size of the block in advance.
81 never gives memory back to the underlying allocator. Free sub-blocks
82 are just made available to later calls of
85 Don't try to free blocks allocated by
87 to the underlying arena's
89 function, or to try freeing blocks obtained directly from the arena's
93 If you do, you'll get what you deserve.
99 are intended to provide a slightly more natural interface to
102 mystruct *p = subarena_alloc(s, sizeof(mystruct));
106 mystruct p = A_CREATE(s, mystruct);
108 Similarly, the block can be freed by saying
112 rather than the more cumbersome
114 subarena_free(s, p, sizeof(*p));
116 There is a standard subarena
120 as its underlying allocator (obtained the first time the subarena is
133 ought to be called before any of the other functions as a matter of good
134 taste, but actually the system will initialize itself the first time
142 Mark Wooding, <mdw@distorted.org.uk>