@@@ much mess, mostly manpages

[mLib] / mem / pool.3.in

.\" -*-nroff-*-
.\"
.\" Manual for resource pools
.\"
.\" (c) 2000, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH pool 3mLib "7 July 2000" "Straylight/Edgeware" "mLib utilities library"
.\" @pool_alloc
.\" @pool_strdup
.\" @pool_init
.\" @pool_create
.\" @pool_destroy
.\" @pool_sub
.\" @pool_add
.\" @POOL_ADD
.\" @pool_fopen
.\" @pool_fclose
.\" @pool_subarena
.
.\"--------------------------------------------------------------------------
.SH "NAME"
pool \- resource pool management
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.nf
.B "#include <mLib/pool.h>"
.PP
.B "typedef struct { ...\& } pool;"
.PP
.ta 2n
.B "typedef struct {"
.B "	pool_resource *next;"
.BI "	void (*destroy)(pool_resource *" r );
.B "} pool_resource;"
.PP
.B "typedef struct {"
.B "	FILE *fp;"
.B "	..."
.B "} pool_file;"
.PP
.BI "void pool_init(pool *" p ", arena *" a );
.BI "pool *pool_create(arena *" a );
.BI "pool *pool_sub(pool *" p );
.BI "void pool_destroy(pool *" p );
.ta \w'\fBvoid pool_add('u
.BI "void pool_add(pool *" p ", pool_resource *" r ,
.BI "	void (*" dfn ")(pool_resource *" r ));
.BI "void *pool_alloc(pool *" p ", size_t " sz );
.BI "char *pool_strdup(pool *" p ", const char *" s );
.BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how );
.BI "int pool_fclose(pool_file *" pf );
.BI "subarena *pool_subarena(pool *" p );
.PP
.ta \w'\fBvoid POOL_ADD('u
.BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
.BI "	void (*" dfn ")(pool_resource *" r ));
.fi
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
.SS "Overview"
A
.I "resource pool"
is a collection of resources (e.g., memory, files) which may be disposed
of simultaneously.
.PP
A pool may be a
.IR "root pool" ,
in which case it stands on its own, or it may be a
.IR "subpool"
of another pool (which may in turn either be a root pool or a subpool of
another).
.PP
Pools manage memory efficiently.  Memory is allocated in large chunks
from an
.BR arena (3),
and given out as necessary to callers.  There is no way of freeing
memory dynamically; instead, the memory allocated by a pool is freed
when the pool is destroyed.  While allocation is rapid, there is waste
because the allocator has to ensure that blocks are properly aligned.
Since pools offer an arena interface, it is possible to build a
.BR subarena (3)
over them.  This also enables memory in the subarena to be reclaimed
when the pool is destroyed.
.PP
Other resources (e.g., file handles) may be added to the pool.  The pool
will automatically release any resources it has when it's destroyed.
Attaching resources to an appropriate pool can therefore be a useful way
of avoiding memory leaks.
.
.SS "Creating and destroying pools"
A new root pool is created using
.BR pool_create ,
passing it an arena from which it can allocate large memory blocks.
Alternatively, you can allocate a
.B pool
structure from somewhere and initialize it by passing its address and an
arena to
.BR pool_init .
.PP
A subpool is created by calling
.BR pool_sub ,
naming the parent pool.
.PP
Pools are destroyed by passing them to
.BR pool_destroy .
Pools created by
.B pool_create
are completely destroyed, since the memory containing the pool structure
is allocated from the pool itself.  Subpools and pools allocated by the
caller and initialized by
.BR pool_init ,
on the other hand, are
allocated from a parent pool, and may be reused after being `destroyed'.
.
.SS "Memory allocation"
Memory is allocated from a pool by calling
.BR pool_alloc ,
passing it the pool and the size of memory requested.  There is an
interface for copying strings,
.BR pool_strdup ,
since this is a common operation.  Note that there is no
.BR pool_free :
if this is important, either use the pool's arena
.B p->pa
directly or create a subpool.
.PP
A pool provides an
.BR arena (3)
interface,
.BR p->a ,
which can be passed to other components to cause them to use the pool
for memory allocation.
.
.SS "Other resources"
Pool resources have a header of type
.B pool_resource
with the structure shown in the synopsis.  Resources are added to the
pool by passing a pointer to the pool, the resource block and a
destruction function to
.BR pool_add .
.PP
If your resource is freed before the pool is destroyed, manually zero
the
.B destroy
field in the resource header to let the pool manager know not to free
the resource again.
.PP
It's usual to allocate the resource structures from the pool's arena so
that they're automatically freed when the pool is destroyed.
.PP
A
.BR subarena (3)
may be created for a particular pool by calling
.BR pool_subarena .
The subarena and its contents will be freed automatically when the pool
is destroyed.
.PP
Files may be opened and registered with a pool by
.BR pool_fopen :
the
.I pool
argument specifies which pool, and the
.I file
and
.I how
arguments are passed to the standard
.BR fopen (3)
function.  The return value is a pointer to a
.B pool_file
structure, containing a member
.B fp
which is the actual file handle.  Don't call
.B fclose
directly on the file handle: instead pass the whole structure to
.B pool_fclose
which will ensure that it doesn't get closed twice by accident.  It's
advisable to close files by hand, to prevent the process from running
out; it's just not a disaster if you forget by accident.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR alloc (3),
.BR arena (3),
.BR mLib (3),
.BR sub (3).
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------