chiark / gitweb /
Update manual style.
[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 .\" @sub_alloc
18 .\" @sub_free
19 .\" @sub_init
20 .\"
21 .\" @CREATE
22 .\" @DESTROY
23 .\"
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
44 .BR xmalloc (3),
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
73 .BR xmalloc (3)
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
97 rather than the more cumbersome
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.
106 .SH "SEE ALSO"
107 .BR exc (3),
108 .BR alloc (3),
109 .BR mLib (3).
110 .SH AUTHOR
111 Mark Wooding, <mdw@nsict.org>