Improvements to increase clarity, fix misstatements, add missing

[rsync/rsync.git] / lib / pool_alloc.3

.ds d \-\^\-
.ds o \fR[\fP
.ds c \fR]\fP
.ds | \fR|\fP
.de D
\\.B \*d\\$1
..
.de DI
\\.BI \*d\\$1 \\$2
..
.de DR
\\.BR \*d\\$1 \\$2
..
.de Di
\\.BI \*d\\$1 " \\$2"
..
.de Db
\\.B \*d\\$1 " \\$2"
..
.de Df
\\.B \*d\*ono\*c\\$1
..
.de See
See \fB\\$1\fP for details.
..
.de SeeIn
See \fB\\$1\fP in \fB\\$2\fP for details.
..
.TH POOL_ALLOC 3
.SH NAME
pool_alloc, pool_free, pool_talloc, pool_tfree, pool_create, pool_destroy
\- Allocate and free memory in managed allocation pools.
.SH SYNOPSIS
.B #include "pool_alloc.h"

\fBstruct alloc_pool *pool_create(size_t \fIsize\fB, size_t \fIquantum\fB, void (*\fIbomb\fB)(char *), int \fIflags\fB);

\fBvoid pool_destroy(struct alloc_pool *\fIpool\fB);

\fBvoid *pool_alloc(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, char *\fImsg\fB);

\fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB);

\fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB);

\fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB);
.SH DESCRIPTION
.P
The pool allocation routines use
.B malloc()
for underlying memory management.
What allocation pools do is cause memory within a given pool
to be allocated in large contiguous blocks
(called extents) that will be reusable when freed.  Unlike
.BR malloc() ,
the allocations are not managed individually.
Instead, each extent tracks the total free memory within the
extent.  Each extent can either be used to allocate memory
or to manage the freeing of memory within that extent.
When an extent has less free memory than a given
allocation request (or at the request of the user),
memory within that extent ceases to be used for allocation,
and a new extent is added to the pool.
.P
This form of memory management is suited to large numbers of small
related allocations that are held for a while
and then freed as a group.
Because the
underlying allocations are done in large contiguous extents,
when an extent is freed, it releases a large enough
contiguous block of memory to allow the memory to be returned
to the OS for use by whatever program needs it.
You can allocate from one or more memory pools and/or
.B malloc()
all at the same time without interfering with how pools work.
.P
.B pool_create()
Creates an allocation pool for subsequent calls to the pool
allocation functions.
When an extent is created for allocations it will be
.I size 
bytes.
Allocations from the pool have their sizes rounded up to a
multiple of
.I quantum
bytes in length.
Specifying
.B 0
for
.I quantum
will produce a quantum that should meet maximal alignment
on most platforms.
If
.B POOL_QALIGN
is set in the
.IR flags ,
allocations will be aligned to addresses that are a
multiple of
.IR quantum .
If
.B POOL_CLEAR
is set in the
.IR flags ,
all allocations from the pool will be initialized to zeros.
You may specify a
.B NULL
for the
.I bomb
function pointer if you don't wish to use it.  (See the
.B pool_alloc()
function for how it is used.)
.P
.B pool_destroy()
destroys an allocation
.I pool
and frees all its associated memory.
.P
.B pool_alloc()
allocates
.I size
bytes from the specified
.IR pool .
If
.I size
is
.BR 0 ,
.I quantum
bytes will be allocated.
If the pool has been created with
.BR POOL_QALIGN ,
every chunk of memory that is returned will be suitably aligned.
You can use this with the default
.I quantum
size to ensure that all memory can store a variable of any type.
If the requested memory cannot be allocated, the
.I bomb()
function will be called with
.I msg
as its sole argument (if the function was defined at the time
the pool was created), and then a
.B NULL
address is returned (assuming that the bomb function didn't exit).
.P
.B pool_free()
frees
.I size
bytes pointed to by an
.I addr
that was previously allocated in the specified
.IR pool .
If
.I size
is
.BR 0 ,
.I quantum
bytes will be freed.
The memory freed within an extent will not be reusable until
all of the memory in that extent has been freed with one
exception: the most recent pool allocation may be freed back
into the pool prior to making any further allocations.
If enough free calls are made to indicate that an extent has no
remaining allocated objects (as computed by the total freed size for
an extent), its memory will be completely freed back to the system.
If
.I addr
is
.BR 0 ,
no memory will be freed, but subsequent allocations will come
from a new extent.
.P
.B pool_talloc()
is a macro that takes a
.I type
and a
.I count
instead of a
.IR size .
It casts the return value to the correct pointer type.
.P
.B pool_tfree
is a macro that calls
.B pool_free
on memory that was allocated by
.BR pool_talloc() .
.SH RETURN VALUE
.B pool_create()
returns a pointer to
.BR "struct alloc_pool" .
.P
.B pool_alloc()
and
.B pool_talloc()
return pointers to the allocated memory,
or NULL if the request fails.
The return type of
.B pool_alloc()
will normally require casting to the desired type but
.B pool_talloc()
will returns a pointer of the requested
.IR type .
.P
.BR pool_free() ,
.B pool_tfree()
and
.B pool_destroy()
return no value.
.SH SEE ALSO
.nf
malloc(3)
.SH AUTHOR
pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
.SH BUGS AND ISSUES