b6b9d458 |
1 | .\" -*-nroff-*- |
2 | .de VS |
3 | .sp 1 |
4 | .RS 5 |
5 | .nf |
6 | .ft B |
7 | .. |
8 | .de VE |
9 | .ft R |
10 | .fi |
11 | .RE |
12 | .sp 1 |
13 | .. |
14 | .TH sub 3mLib "8 May 1999" mLib |
15 | .SH NAME |
16 | sub \- efficient allocation and freeing of small blocks |
17 | .SH SYNOPSIS |
18 | .nf |
19 | .B "#include <mLib/sub.h>" |
20 | |
21 | .B "void sub_init(void);" |
22 | .BI "void *sub_alloc(size_t " sz ); |
23 | .BI "void sub_free(void *" p ", size_t " sz ); |
24 | |
25 | .BI "void *CREATE(" type ); |
26 | .BI "void DESTROY(" type " *" p ); |
27 | .fi |
28 | .SH DESCRIPTION |
29 | The |
30 | .B sub |
31 | collection of functions and macros implement an efficient allocator for |
32 | small blocks of known sizes. Free blocks of the same size are linked |
33 | together in list, making freeing and allocation fast. The `free' |
34 | operation requires the block size as an argument, so there's no data |
35 | overhead for an allocated block. The system takes advantage of this by |
36 | allocating big chunks from the underlying system (actually via |
37 | .BR xmalloc (3mLib), |
38 | q.v.) and splitting the chunks into smaller blocks of the right size, so |
39 | the space and time overhead from the underlying allocator is divided |
40 | over many blocks. |
41 | .PP |
42 | Calling |
43 | .B sub_alloc |
44 | allocates a block of |
45 | .I sz |
46 | bytes. If there isn't enough memory to allocate the block, the |
47 | exception |
48 | .B EXC_NOMEM |
49 | is raised. |
50 | .PP |
51 | The |
52 | .B sub_free |
53 | function frees a block allocated by |
54 | .BR sub_alloc . |
55 | You must know the size of the block in advance. Note that |
56 | .B sub_free |
57 | never gives memory back to the underlying allocator. Free sub-blocks |
58 | are just made available to later calls of |
59 | .BR sub_alloc . |
60 | .PP |
61 | Don't try to pass blocks allocated by |
62 | .B sub_alloc |
63 | to |
64 | .BR free (3); |
65 | similarly, don't try to pass blocks allocated by |
66 | .BR xmalloc (3mLib) |
67 | or |
68 | .BR malloc (3) |
69 | to |
70 | .BR sub_free . |
71 | If you do, you'll get what you deserve. |
72 | .PP |
73 | The pair of macros |
74 | .B CREATE |
75 | and |
76 | .B DESTROY |
77 | are intended to provide a slightly more natural interface to |
78 | allocation. The call |
79 | .VS |
80 | mystruct *p = sub_alloc(sizeof(mystruct)); |
81 | .VE |
82 | can be replaced by |
83 | .VS |
84 | mystruct p = CREATE(mystruct); |
85 | .VE |
86 | Similarly, the block can be freed by saying |
87 | .VS |
88 | DESTROY(p) |
89 | .VE |
90 | rather than the more cubersome |
91 | .VS |
92 | sub_free(p, sizeof(*p)); |
93 | .VE |
94 | The function |
95 | .B sub_init |
96 | must be called before any of the other |
97 | .B sub |
98 | functions or macros. |
99 | .SH AUTHOR |
100 | Mark Wooding, <mdw@nsict.org> |