+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH pool 3 "7 July 2000" mLib
+.SH "NAME"
+pool \- resource pool management
+.\" @pool_alloc
+.\" @pool_strdup
+.\" @pool_create
+.\" @pool_destroy
+.\" @pool_sub
+.\" @pool_add
+.\" @POOL_ADD
+.\" @pool_fopen
+.\" @pool_fclose
+.\" @pool_subarena
+.SH "SYNOPSIS"
+.nf
+.B "#include <mLib/pool.h>"
+
+.BI "pool *pool_create(arena *" a );
+.BI "pool *pool_sub(pool *" p );
+.BI "void pool_destroy(pool *" p );
+.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 );
+
+.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.
+.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 .
+Root pools are completely destroyed, since the memory containing the
+pool structure is allocated from the pool itself. Subpools, 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:
+.VS
+typedef struct pool_resource {
+ struct pool_resource *next;
+ void (*destroy)(struct pool_resource */*r*/);
+} pool_resource;
+.VE
+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 subarena (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>
~mdw / mLib / commitdiff