[mLib] / man / sub.3

.\" -*-nroff-*-
.de VS
.sp 1
.RS 5
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.TH sub 3 "8 May 1999" mLib
.SH NAME
sub \- efficient allocation and freeing of small blocks
.\" @sub_alloc
.\" @sub_free
.\" @sub_init
.\"
.\" @CREATE
.\" @DESTROY
.\"
.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 (3),
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 (3)
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 "SEE ALSO"
.BR exc (3),
.BR alloc (3),
.BR mLib (3).
.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	..
08da152e	14	.TH sub 3 "8 May 1999" mLib
b6b9d458	15	.SH NAME
b6b9d458	16	sub \- 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
	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
08da152e	44	.BR xmalloc (3),
b6b9d458	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
08da152e	73	.BR xmalloc (3)
b6b9d458	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 cubersome
	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.
08da152e	106	.SH "SEE ALSO"
	107	.BR exc (3),
	108	.BR alloc (3),
	109	.BR mLib (3).
b6b9d458	110	.SH AUTHOR
b6b9d458	111	Mark Wooding, <mdw@nsict.org>