123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255 |
- .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_free_old, pool_talloc, pool_tfree, pool_create, pool_destroy, pool_boundary
- \- 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_free_old(struct alloc_pool *\fIpool\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);
- \fBvoid pool_boundary(struct alloc_pool *\fIpool\fB, sise_t \fIsize\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, the current extent ceases to be used
- for allocation. See also the
- .B pool_boundary()
- function.
- .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 can release 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_free_old()
- takes a boundary
- .I addr
- value that was returned by
- .B pool_boundary()
- and frees up any extents in the
- .I pool
- that have data allocated from that point backward in time.
- NOTE: you must NOT mix calls to both
- .B pool_free
- and
- .B pool_free_old
- on the same pool!
- .P
- .B pool_boundary()
- asks for a boundary value that can be sent to
- .B pool_free_old()
- at a later time to free up all memory allocated prior to a particular
- moment in time.
- If the extent that holds the boundary point has allocations from after the
- boundary point, it will not be freed until a future
- .B pool_free_old()
- call encompasses the entirety of the extent's data.
- If
- .I len
- is non-zero, the call will also check if the active extent has at least
- that much free memory available in it, and if not, it will mark the
- extent as inactive, forcing a new extent to be used for future allocations.
- (You can specify -1 for
- .I len
- if you want to force a new extent to start.)
- .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
- .B pool_boundary()
- returns a pointer that should only be used in a call to
- .BR pool_free_old() .
- .P
- .BR pool_free() ,
- .BR pool_free_old() ,
- .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
|