Annotation of embedaddon/rsync/lib/pool_alloc.3, revision 1.1
1.1 ! misho 1: .ds d \-\^\-
! 2: .ds o \fR[\fP
! 3: .ds c \fR]\fP
! 4: .ds | \fR|\fP
! 5: .de D
! 6: \\.B \*d\\$1
! 7: ..
! 8: .de DI
! 9: \\.BI \*d\\$1 \\$2
! 10: ..
! 11: .de DR
! 12: \\.BR \*d\\$1 \\$2
! 13: ..
! 14: .de Di
! 15: \\.BI \*d\\$1 " \\$2"
! 16: ..
! 17: .de Db
! 18: \\.B \*d\\$1 " \\$2"
! 19: ..
! 20: .de Df
! 21: \\.B \*d\*ono\*c\\$1
! 22: ..
! 23: .de See
! 24: See \fB\\$1\fP for details.
! 25: ..
! 26: .de SeeIn
! 27: See \fB\\$1\fP in \fB\\$2\fP for details.
! 28: ..
! 29: .TH POOL_ALLOC 3
! 30: .SH NAME
! 31: pool_alloc, pool_free, pool_free_old, pool_talloc, pool_tfree, pool_create, pool_destroy, pool_boundary
! 32: \- Allocate and free memory in managed allocation pools.
! 33: .SH SYNOPSIS
! 34: .B #include "pool_alloc.h"
! 35:
! 36: \fBstruct alloc_pool *pool_create(size_t \fIsize\fB, size_t \fIquantum\fB, void (*\fIbomb\fB)(char *), int \fIflags\fB);
! 37:
! 38: \fBvoid pool_destroy(struct alloc_pool *\fIpool\fB);
! 39:
! 40: \fBvoid *pool_alloc(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, char *\fImsg\fB);
! 41:
! 42: \fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB);
! 43:
! 44: \fBvoid pool_free_old(struct alloc_pool *\fIpool\fB, void *\fIaddr\fB);
! 45:
! 46: \fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB);
! 47:
! 48: \fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB);
! 49:
! 50: \fBvoid pool_boundary(struct alloc_pool *\fIpool\fB, sise_t \fIsize\fB);
! 51: .SH DESCRIPTION
! 52: .P
! 53: The pool allocation routines use
! 54: .B malloc()
! 55: for underlying memory management.
! 56: What allocation pools do is cause memory within a given pool
! 57: to be allocated in large contiguous blocks
! 58: (called extents) that will be reusable when freed. Unlike
! 59: .BR malloc() ,
! 60: the allocations are not managed individually.
! 61: Instead, each extent tracks the total free memory within the
! 62: extent. Each extent can either be used to allocate memory
! 63: or to manage the freeing of memory within that extent.
! 64: When an extent has less free memory than a given
! 65: allocation request, the current extent ceases to be used
! 66: for allocation. See also the
! 67: .B pool_boundary()
! 68: function.
! 69: .P
! 70: This form of memory management is suited to large numbers of small
! 71: related allocations that are held for a while
! 72: and then freed as a group.
! 73: Because the
! 74: underlying allocations are done in large contiguous extents,
! 75: when an extent is freed, it can release a large enough
! 76: contiguous block of memory to allow the memory to be returned
! 77: to the OS for use by whatever program needs it.
! 78: You can allocate from one or more memory pools and/or
! 79: .B malloc()
! 80: all at the same time without interfering with how pools work.
! 81: .P
! 82: .B pool_create()
! 83: Creates an allocation pool for subsequent calls to the pool
! 84: allocation functions.
! 85: When an extent is created for allocations it will be
! 86: .I size
! 87: bytes.
! 88: Allocations from the pool have their sizes rounded up to a
! 89: multiple of
! 90: .I quantum
! 91: bytes in length.
! 92: Specifying
! 93: .B 0
! 94: for
! 95: .I quantum
! 96: will produce a quantum that should meet maximal alignment
! 97: on most platforms.
! 98: If
! 99: .B POOL_QALIGN
! 100: is set in the
! 101: .IR flags ,
! 102: allocations will be aligned to addresses that are a
! 103: multiple of
! 104: .IR quantum .
! 105: If
! 106: .B POOL_CLEAR
! 107: is set in the
! 108: .IR flags ,
! 109: all allocations from the pool will be initialized to zeros.
! 110: You may specify a
! 111: .B NULL
! 112: for the
! 113: .I bomb
! 114: function pointer if you don't wish to use it. (See the
! 115: .B pool_alloc()
! 116: function for how it is used.)
! 117: .P
! 118: .B pool_destroy()
! 119: destroys an allocation
! 120: .I pool
! 121: and frees all its associated memory.
! 122: .P
! 123: .B pool_alloc()
! 124: allocates
! 125: .I size
! 126: bytes from the specified
! 127: .IR pool .
! 128: If
! 129: .I size
! 130: is
! 131: .BR 0 ,
! 132: .I quantum
! 133: bytes will be allocated.
! 134: If the pool has been created with
! 135: .BR POOL_QALIGN ,
! 136: every chunk of memory that is returned will be suitably aligned.
! 137: You can use this with the default
! 138: .I quantum
! 139: size to ensure that all memory can store a variable of any type.
! 140: If the requested memory cannot be allocated, the
! 141: .I bomb()
! 142: function will be called with
! 143: .I msg
! 144: as its sole argument (if the function was defined at the time
! 145: the pool was created), and then a
! 146: .B NULL
! 147: address is returned (assuming that the bomb function didn't exit).
! 148: .P
! 149: .B pool_free()
! 150: frees
! 151: .I size
! 152: bytes pointed to by an
! 153: .I addr
! 154: that was previously allocated in the specified
! 155: .IR pool .
! 156: If
! 157: .I size
! 158: is
! 159: .BR 0 ,
! 160: .I quantum
! 161: bytes will be freed.
! 162: The memory freed within an extent will not be reusable until
! 163: all of the memory in that extent has been freed with one
! 164: exception: the most recent pool allocation may be freed back
! 165: into the pool prior to making any further allocations.
! 166: If enough free calls are made to indicate that an extent has no
! 167: remaining allocated objects (as computed by the total freed size for
! 168: an extent), its memory will be completely freed back to the system.
! 169: If
! 170: .I addr
! 171: is
! 172: .BR 0 ,
! 173: no memory will be freed, but subsequent allocations will come
! 174: from a new extent.
! 175: .P
! 176: .B pool_free_old()
! 177: takes a boundary
! 178: .I addr
! 179: value that was returned by
! 180: .B pool_boundary()
! 181: and frees up any extents in the
! 182: .I pool
! 183: that have data allocated from that point backward in time.
! 184: NOTE: you must NOT mix calls to both
! 185: .B pool_free
! 186: and
! 187: .B pool_free_old
! 188: on the same pool!
! 189: .P
! 190: .B pool_boundary()
! 191: asks for a boundary value that can be sent to
! 192: .B pool_free_old()
! 193: at a later time to free up all memory allocated prior to a particular
! 194: moment in time.
! 195: If the extent that holds the boundary point has allocations from after the
! 196: boundary point, it will not be freed until a future
! 197: .B pool_free_old()
! 198: call encompasses the entirety of the extent's data.
! 199: If
! 200: .I len
! 201: is non-zero, the call will also check if the active extent has at least
! 202: that much free memory available in it, and if not, it will mark the
! 203: extent as inactive, forcing a new extent to be used for future allocations.
! 204: (You can specify -1 for
! 205: .I len
! 206: if you want to force a new extent to start.)
! 207: .P
! 208: .B pool_talloc()
! 209: is a macro that takes a
! 210: .I type
! 211: and a
! 212: .I count
! 213: instead of a
! 214: .IR size .
! 215: It casts the return value to the correct pointer type.
! 216: .P
! 217: .B pool_tfree
! 218: is a macro that calls
! 219: .B pool_free
! 220: on memory that was allocated by
! 221: .BR pool_talloc() .
! 222: .SH RETURN VALUE
! 223: .B pool_create()
! 224: returns a pointer to
! 225: .BR "struct alloc_pool" .
! 226: .P
! 227: .B pool_alloc()
! 228: and
! 229: .B pool_talloc()
! 230: return pointers to the allocated memory,
! 231: or NULL if the request fails.
! 232: The return type of
! 233: .B pool_alloc()
! 234: will normally require casting to the desired type but
! 235: .B pool_talloc()
! 236: will returns a pointer of the requested
! 237: .IR type .
! 238: .P
! 239: .B pool_boundary()
! 240: returns a pointer that should only be used in a call to
! 241: .BR pool_free_old() .
! 242: .P
! 243: .BR pool_free() ,
! 244: .BR pool_free_old() ,
! 245: .B pool_tfree()
! 246: and
! 247: .B pool_destroy()
! 248: return no value.
! 249: .SH SEE ALSO
! 250: .nf
! 251: malloc(3)
! 252: .SH AUTHOR
! 253: pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
! 254: .SH BUGS AND ISSUES
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pool_alloc.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / lib