[mLib] / man / sub.3

.\" -*-nroff-*-
.de VS
.sp 1
.RS 5
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.TH sub 3mLib "8 May 1999" mLib
.SH NAME
sub \- efficient allocation and freeing of small blocks
.SH SYNOPSIS
.nf
.B "#include <mLib/sub.h>"

.B "void sub_init(void);"
.BI "void *sub_alloc(size_t " sz );
.BI "void sub_free(void *" p ", size_t " sz );

.BI "void *CREATE(" type );
.BI "void DESTROY(" type " *" p );
.fi
.SH DESCRIPTION
The
.B sub
collection of functions and macros implement an efficient allocator for
small blocks of known sizes.  Free blocks of the same size are linked
together in list, making freeing and allocation fast.  The `free'
operation requires the block size as an argument, so there's no data
overhead for an allocated block.  The system takes advantage of this by
allocating big chunks from the underlying system (actually via
.BR xmalloc (3mLib),
q.v.) and splitting the chunks into smaller blocks of the right size, so
the space and time overhead from the underlying allocator is divided
over many blocks.
.PP
Calling
.B sub_alloc
allocates a block of
.I sz
bytes.  If there isn't enough memory to allocate the block, the
exception
.B EXC_NOMEM
is raised.
.PP
The
.B sub_free
function frees a block allocated by
.BR sub_alloc .
You must know the size of the block in advance.  Note that
.B sub_free
never gives memory back to the underlying allocator.  Free sub-blocks
are just made available to later calls of
.BR sub_alloc .
.PP
Don't try to pass blocks allocated by
.B sub_alloc
to
.BR free (3);
similarly, don't try to pass blocks allocated by
.BR xmalloc (3mLib)
or
.BR malloc (3)
to
.BR sub_free .
If you do, you'll get what you deserve.
.PP
The pair of macros
.B CREATE
and
.B DESTROY
are intended to provide a slightly more natural interface to
allocation.  The call
.VS
mystruct *p = sub_alloc(sizeof(mystruct));
.VE
can be replaced by
.VS
mystruct p = CREATE(mystruct);
.VE
Similarly, the block can be freed by saying
.VS
DESTROY(p)
.VE
rather than the more cubersome
.VS
sub_free(p, sizeof(*p));
.VE
The function
.B sub_init
must be called before any of the other
.B sub
functions or macros.
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
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>