chiark / gitweb /
Update manual style.
[mLib] / man / sub.3
CommitLineData
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
16sub \- 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
36The
37.B sub
38collection of functions and macros implement an efficient allocator for
39small blocks of known sizes. Free blocks of the same size are linked
40together in list, making freeing and allocation fast. The `free'
41operation requires the block size as an argument, so there's no data
42overhead for an allocated block. The system takes advantage of this by
43allocating big chunks from the underlying system (actually via
08da152e 44.BR xmalloc (3),
b6b9d458 45q.v.) and splitting the chunks into smaller blocks of the right size, so
46the space and time overhead from the underlying allocator is divided
47over many blocks.
48.PP
49Calling
50.B sub_alloc
51allocates a block of
52.I sz
53bytes. If there isn't enough memory to allocate the block, the
54exception
55.B EXC_NOMEM
56is raised.
57.PP
58The
59.B sub_free
60function frees a block allocated by
61.BR sub_alloc .
62You must know the size of the block in advance. Note that
63.B sub_free
64never gives memory back to the underlying allocator. Free sub-blocks
65are just made available to later calls of
66.BR sub_alloc .
67.PP
68Don't try to pass blocks allocated by
69.B sub_alloc
70to
71.BR free (3);
72similarly, don't try to pass blocks allocated by
08da152e 73.BR xmalloc (3)
b6b9d458 74or
75.BR malloc (3)
76to
77.BR sub_free .
78If you do, you'll get what you deserve.
79.PP
80The pair of macros
81.B CREATE
82and
83.B DESTROY
84are intended to provide a slightly more natural interface to
85allocation. The call
86.VS
87mystruct *p = sub_alloc(sizeof(mystruct));
88.VE
89can be replaced by
90.VS
91mystruct p = CREATE(mystruct);
92.VE
93Similarly, the block can be freed by saying
94.VS
95DESTROY(p)
96.VE
d2a91066 97rather than the more cumbersome
b6b9d458 98.VS
99sub_free(p, sizeof(*p));
100.VE
101The function
102.B sub_init
103must be called before any of the other
104.B sub
105functions or macros.
08da152e 106.SH "SEE ALSO"
107.BR exc (3),
108.BR alloc (3),
109.BR mLib (3).
b6b9d458 110.SH AUTHOR
111Mark Wooding, <mdw@nsict.org>