chiark / gitweb /
b1f608302a54ff28da1a88fcbab5693a2f860e2d
[mLib] / man / sub.3
1 .\" -*-nroff-*-
2 .de VS
3 .sp 1
4 .RS
5 .nf
6 .ft B
7 ..
8 .de VE
9 .ft R
10 .fi
11 .RE
12 .sp 1
13 ..
14 .TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
15 .SH NAME
16 sub \- efficient allocation and freeing of small blocks
17 .\" @subarena_create
18 .\" @subarena_destroy
19 .\" @subarena_alloc
20 .\" @subarena_free
21 .\" @sub_alloc
22 .\" @sub_free
23 .\" @sub_init
24 .\"
25 .\" @A_CREATE
26 .\" @A_DESTROY
27 .\" @CREATE
28 .\" @DESTROY
29 .\"
30 .SH SYNOPSIS
31 .nf
32 .B "#include <mLib/sub.h>"
33
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 );
38
39 .B "void sub_init(void);"
40 .BI "void *sub_alloc(size_t " sz );
41 .BI "void sub_free(void *" p ", size_t " sz );
42
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 );
47 .fi
48 .SH DESCRIPTION
49 The
50 .B subarena
51 collection of functions and macros implement an efficient allocator for
52 small blocks of known sizes, constructed from a general allocator
53 implemented by an
54 .BR arena (3).
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.
62 .PP
63 Calling
64 .B subarena_alloc
65 allocates a block of
66 .I sz
67 bytes from the subarena
68 .IR s .
69 If there isn't enough memory to allocate the block, the
70 exception
71 .B EXC_NOMEM
72 is raised.
73 .PP
74 The
75 .B subarena_free
76 function frees a block allocated by
77 .B subarena_alloc
78 from the same subarena.  You must know the size of the block in advance.
79 Note that
80 .B subarena_free
81 never gives memory back to the underlying allocator.  Free sub-blocks
82 are just made available to later calls of
83 .BR subarena_alloc .
84 .PP
85 Don't try to free blocks allocated by
86 .B subarena_alloc
87 to the underlying arena's
88 .I free
89 function, or to try freeing blocks obtained directly from the arena's
90 .I alloc
91 function using
92 .BR subarena_free .
93 If you do, you'll get what you deserve.
94 .PP
95 The pair of macros
96 .B A_CREATE
97 and
98 .B A_DESTROY
99 are intended to provide a slightly more natural interface to
100 allocation.  The call
101 .VS
102 mystruct *p = subarena_alloc(s, sizeof(mystruct));
103 .VE
104 can be replaced by
105 .VS
106 mystruct p = A_CREATE(s, mystruct);
107 .VE
108 Similarly, the block can be freed by saying
109 .VS
110 A_DESTROY(s, p)
111 .VE
112 rather than the more cumbersome
113 .VS
114 subarena_free(s, p, sizeof(*p));
115 .VE
116 There is a standard subarena
117 .B sub_global
118 which uses
119 .B arena_global
120 as its underlying allocator (obtained the first time the subarena is
121 used).  The functions
122 .B sub_alloc
123 and
124 .B sub_free
125 and the macros
126 .B CREATE
127 and
128 .B DESTROY
129 use this subarena.
130 .PP
131 The function
132 .B sub_init
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
135 it's used.
136 .SH "SEE ALSO"
137 .BR arena (3),
138 .BR exc (3),
139 .BR alloc (3),
140 .BR mLib (3).
141 .SH AUTHOR
142 Mark Wooding, <mdw@distorted.org.uk>