b6b9d458 |
1 | .\" -*-nroff-*- |
2 | .de VS |
3 | .sp 1 |
d66d7727 |
4 | .RS |
b6b9d458 |
5 | .nf |
6 | .ft B |
7 | .. |
8 | .de VE |
9 | .ft R |
10 | .fi |
11 | .RE |
12 | .sp 1 |
13 | .. |
fbf20b5b |
14 | .TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library" |
b6b9d458 |
15 | .SH NAME |
16 | sub \- efficient allocation and freeing of small blocks |
c5775f49 |
17 | .\" @subarena_create |
18 | .\" @subarena_destroy |
19 | .\" @subarena_alloc |
20 | .\" @subarena_free |
08da152e |
21 | .\" @sub_alloc |
22 | .\" @sub_free |
23 | .\" @sub_init |
24 | .\" |
c5775f49 |
25 | .\" @A_CREATE |
26 | .\" @A_DESTROY |
08da152e |
27 | .\" @CREATE |
28 | .\" @DESTROY |
29 | .\" |
b6b9d458 |
30 | .SH SYNOPSIS |
31 | .nf |
32 | .B "#include <mLib/sub.h>" |
33 | |
c5775f49 |
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 | |
b6b9d458 |
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 | |
c5775f49 |
43 | .BI "void *A_CREATE(subarena *" s ", " type ); |
44 | .BI "void A_DESTROY(subarena *" s ", " type " *" p ); |
b6b9d458 |
45 | .BI "void *CREATE(" type ); |
46 | .BI "void DESTROY(" type " *" p ); |
47 | .fi |
48 | .SH DESCRIPTION |
49 | The |
c5775f49 |
50 | .B subarena |
b6b9d458 |
51 | collection of functions and macros implement an efficient allocator for |
c5775f49 |
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. |
b6b9d458 |
62 | .PP |
63 | Calling |
c5775f49 |
64 | .B subarena_alloc |
b6b9d458 |
65 | allocates a block of |
66 | .I sz |
c5775f49 |
67 | bytes from the subarena |
d4efbcd9 |
68 | .IR s . |
c5775f49 |
69 | If there isn't enough memory to allocate the block, the |
b6b9d458 |
70 | exception |
71 | .B EXC_NOMEM |
72 | is raised. |
73 | .PP |
74 | The |
c5775f49 |
75 | .B subarena_free |
b6b9d458 |
76 | function frees a block allocated by |
c5775f49 |
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 |
b6b9d458 |
81 | never gives memory back to the underlying allocator. Free sub-blocks |
82 | are just made available to later calls of |
c5775f49 |
83 | .BR subarena_alloc . |
b6b9d458 |
84 | .PP |
c5775f49 |
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 |
d4efbcd9 |
90 | .I alloc |
c5775f49 |
91 | function using |
92 | .BR subarena_free . |
b6b9d458 |
93 | If you do, you'll get what you deserve. |
94 | .PP |
95 | The pair of macros |
c5775f49 |
96 | .B A_CREATE |
b6b9d458 |
97 | and |
c5775f49 |
98 | .B A_DESTROY |
b6b9d458 |
99 | are intended to provide a slightly more natural interface to |
100 | allocation. The call |
101 | .VS |
c5775f49 |
102 | mystruct *p = subarena_alloc(s, sizeof(mystruct)); |
b6b9d458 |
103 | .VE |
104 | can be replaced by |
105 | .VS |
c5775f49 |
106 | mystruct p = A_CREATE(s, mystruct); |
b6b9d458 |
107 | .VE |
108 | Similarly, the block can be freed by saying |
109 | .VS |
c5775f49 |
110 | A_DESTROY(s, p) |
b6b9d458 |
111 | .VE |
d2a91066 |
112 | rather than the more cumbersome |
b6b9d458 |
113 | .VS |
c5775f49 |
114 | subarena_free(s, p, sizeof(*p)); |
b6b9d458 |
115 | .VE |
c5775f49 |
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 |
b6b9d458 |
131 | The function |
132 | .B sub_init |
c5775f49 |
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. |
08da152e |
136 | .SH "SEE ALSO" |
c5775f49 |
137 | .BR arena (3), |
08da152e |
138 | .BR exc (3), |
139 | .BR alloc (3), |
140 | .BR mLib (3). |
b6b9d458 |
141 | .SH AUTHOR |
9b5ac6ff |
142 | Mark Wooding, <mdw@distorted.org.uk> |