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 | .. |
08da152e |
14 | .TH sub 3 "8 May 1999" mLib |
b6b9d458 |
15 | .SH NAME |
16 | sub \- efficient allocation and freeing of small blocks |
08da152e |
17 | .\" @sub_alloc |
18 | .\" @sub_free |
19 | .\" @sub_init |
20 | .\" |
21 | .\" @CREATE |
22 | .\" @DESTROY |
23 | .\" |
b6b9d458 |
24 | .SH SYNOPSIS |
25 | .nf |
26 | .B "#include <mLib/sub.h>" |
27 | |
28 | .B "void sub_init(void);" |
29 | .BI "void *sub_alloc(size_t " sz ); |
30 | .BI "void sub_free(void *" p ", size_t " sz ); |
31 | |
32 | .BI "void *CREATE(" type ); |
33 | .BI "void DESTROY(" type " *" p ); |
34 | .fi |
35 | .SH DESCRIPTION |
36 | The |
37 | .B sub |
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 |
08da152e |
44 | .BR xmalloc (3), |
b6b9d458 |
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 |
47 | over many blocks. |
48 | .PP |
49 | Calling |
50 | .B sub_alloc |
51 | allocates a block of |
52 | .I sz |
53 | bytes. If there isn't enough memory to allocate the block, the |
54 | exception |
55 | .B EXC_NOMEM |
56 | is raised. |
57 | .PP |
58 | The |
59 | .B sub_free |
60 | function frees a block allocated by |
61 | .BR sub_alloc . |
62 | You must know the size of the block in advance. Note that |
63 | .B sub_free |
64 | never gives memory back to the underlying allocator. Free sub-blocks |
65 | are just made available to later calls of |
66 | .BR sub_alloc . |
67 | .PP |
68 | Don't try to pass blocks allocated by |
69 | .B sub_alloc |
70 | to |
71 | .BR free (3); |
72 | similarly, don't try to pass blocks allocated by |
08da152e |
73 | .BR xmalloc (3) |
b6b9d458 |
74 | or |
75 | .BR malloc (3) |
76 | to |
77 | .BR sub_free . |
78 | If you do, you'll get what you deserve. |
79 | .PP |
80 | The pair of macros |
81 | .B CREATE |
82 | and |
83 | .B DESTROY |
84 | are intended to provide a slightly more natural interface to |
85 | allocation. The call |
86 | .VS |
87 | mystruct *p = sub_alloc(sizeof(mystruct)); |
88 | .VE |
89 | can be replaced by |
90 | .VS |
91 | mystruct p = CREATE(mystruct); |
92 | .VE |
93 | Similarly, the block can be freed by saying |
94 | .VS |
95 | DESTROY(p) |
96 | .VE |
d2a91066 |
97 | rather than the more cumbersome |
b6b9d458 |
98 | .VS |
99 | sub_free(p, sizeof(*p)); |
100 | .VE |
101 | The function |
102 | .B sub_init |
103 | must be called before any of the other |
104 | .B sub |
105 | functions or macros. |
08da152e |
106 | .SH "SEE ALSO" |
107 | .BR exc (3), |
108 | .BR alloc (3), |
109 | .BR mLib (3). |
b6b9d458 |
110 | .SH AUTHOR |
111 | Mark Wooding, <mdw@nsict.org> |