chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / mem / 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
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
49The
c5775f49 50.B subarena
b6b9d458 51collection of functions and macros implement an efficient allocator for
c5775f49 52small blocks of known sizes, constructed from a general allocator
53implemented by an
54.BR arena (3).
55Free blocks of the same size are linked together in list, making freeing
56and allocation fast. The `free' operation requires the block size as an
57argument, so there's no data overhead for an allocated block. The
58system takes advantage of this by allocating big chunks from the
59underlying arena and splitting the chunks into smaller blocks of the
60right size, so the space and time overhead from the underlying allocator
61is divided over many blocks.
b6b9d458 62.PP
63Calling
c5775f49 64.B subarena_alloc
b6b9d458 65allocates a block of
66.I sz
c5775f49 67bytes from the subarena
d4efbcd9 68.IR s .
c5775f49 69If there isn't enough memory to allocate the block, the
b6b9d458 70exception
71.B EXC_NOMEM
72is raised.
73.PP
74The
c5775f49 75.B subarena_free
b6b9d458 76function frees a block allocated by
c5775f49 77.B subarena_alloc
78from the same subarena. You must know the size of the block in advance.
79Note that
80.B subarena_free
b6b9d458 81never gives memory back to the underlying allocator. Free sub-blocks
82are just made available to later calls of
c5775f49 83.BR subarena_alloc .
b6b9d458 84.PP
c5775f49 85Don't try to free blocks allocated by
86.B subarena_alloc
87to the underlying arena's
88.I free
89function, or to try freeing blocks obtained directly from the arena's
d4efbcd9 90.I alloc
c5775f49 91function using
92.BR subarena_free .
b6b9d458 93If you do, you'll get what you deserve.
94.PP
95The pair of macros
c5775f49 96.B A_CREATE
b6b9d458 97and
c5775f49 98.B A_DESTROY
b6b9d458 99are intended to provide a slightly more natural interface to
100allocation. The call
101.VS
c5775f49 102mystruct *p = subarena_alloc(s, sizeof(mystruct));
b6b9d458 103.VE
104can be replaced by
105.VS
c5775f49 106mystruct p = A_CREATE(s, mystruct);
b6b9d458 107.VE
108Similarly, the block can be freed by saying
109.VS
c5775f49 110A_DESTROY(s, p)
b6b9d458 111.VE
d2a91066 112rather than the more cumbersome
b6b9d458 113.VS
c5775f49 114subarena_free(s, p, sizeof(*p));
b6b9d458 115.VE
c5775f49 116There is a standard subarena
117.B sub_global
118which uses
119.B arena_global
120as its underlying allocator (obtained the first time the subarena is
121used). The functions
122.B sub_alloc
123and
124.B sub_free
125and the macros
126.B CREATE
127and
128.B DESTROY
129use this subarena.
130.PP
b6b9d458 131The function
132.B sub_init
c5775f49 133ought to be called before any of the other functions as a matter of good
134taste, but actually the system will initialize itself the first time
135it'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 142Mark Wooding, <mdw@distorted.org.uk>