Return to pool_alloc.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / lib

rsync 3.2.3

    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*,char*,int), 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: Unless
   99: .B POOL_NO_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: A
  106: .B NULL
  107: may be specified for the
  108: .I bomb
  109: function pointer if it is not needed.  (See the
  110: .B pool_alloc()
  111: function for how it is used.)
  112: If
  113: .B POOL_CLEAR
  114: is set in the
  115: .IR flags ,
  116: all allocations from the pool will be initialized to zeros.
  117: If either
  118: .B POOL_PREPEND
  119: or
  120: .B POOL_INTERN
  121: is specified in the
  122: .IR flags ,
  123: each extent's data structure will be allocated at the start of the
  124: .IR size -length
  125: buffer (rather than as a separate, non-pool allocation), with the
  126: former extending the
  127: .I size
  128: to hold the structure, and the latter subtracting the structure's
  129: length from the indicated
  130: .IR size .
  131: .P
  132: .B pool_destroy()
  133: destroys an allocation
  134: .I pool
  135: and frees all its associated memory.
  136: .P
  137: .B pool_alloc()
  138: allocates
  139: .I size
  140: bytes from the specified
  141: .IR pool .
  142: If
  143: .I size
  144: is
  145: .BR 0 ,
  146: .I quantum
  147: bytes will be allocated.
  148: If the pool has been created without
  149: .BR POOL_NO_QALIGN ,
  150: every chunk of memory that is returned will be suitably aligned.
  151: You can use this with the default
  152: .I quantum
  153: size to ensure that all memory can store a variable of any type.
  154: If the requested memory cannot be allocated, the
  155: .I bomb()
  156: function will be called with
  157: .I msg
  158: as its sole argument (if the function was defined at the time
  159: the pool was created), and then a
  160: .B NULL
  161: address is returned (assuming that the bomb function didn't exit).
  162: .P
  163: .B pool_free()
  164: frees
  165: .I size
  166: bytes pointed to by an
  167: .I addr
  168: that was previously allocated in the specified
  169: .IR pool .
  170: If
  171: .I size
  172: is
  173: .BR 0 ,
  174: .I quantum
  175: bytes will be freed.
  176: The memory freed within an extent will not be reusable until
  177: all of the memory in that extent has been freed with one
  178: exception: the most recent pool allocation may be freed back
  179: into the pool prior to making any further allocations.
  180: If enough free calls are made to indicate that an extent has no
  181: remaining allocated objects (as computed by the total freed size for
  182: an extent), its memory will be completely freed back to the system.
  183: If
  184: .I addr
  185: is
  186: .BR NULL ,
  187: no memory will be freed, but subsequent allocations will come
  188: from a new extent.
  189: .P
  190: .B pool_free_old()
  191: takes a boundary
  192: .I addr
  193: value that was returned by
  194: .B pool_boundary()
  195: and frees up any extents in the
  196: .I pool
  197: that have data allocated from that point backward in time.
  198: NOTE: you must NOT mix calls to both
  199: .B pool_free
  200: and
  201: .B pool_free_old
  202: on the same pool!
  203: .P
  204: .B pool_boundary()
  205: asks for a boundary value that can be sent to 
  206: .B pool_free_old()
  207: at a later time to free up all memory allocated prior to a particular
  208: moment in time.
  209: If the extent that holds the boundary point has allocations from after the
  210: boundary point, it will not be freed until a future
  211: .B pool_free_old()
  212: call encompasses the entirety of the extent's data.
  213: If
  214: .I len
  215: is non-zero, the call will also check if the active extent has at least
  216: that much free memory available in it, and if not, it will mark the
  217: extent as inactive, forcing a new extent to be used for future allocations.
  218: (You can specify -1 for
  219: .I len
  220: if you want to force a new extent to start.)
  221: .P
  222: .B pool_talloc()
  223: is a macro that takes a
  224: .I type
  225: and a
  226: .I count
  227: instead of a
  228: .IR size .
  229: It casts the return value to the correct pointer type.
  230: .P
  231: .B pool_tfree
  232: is a macro that calls
  233: .B pool_free
  234: on memory that was allocated by
  235: .BR pool_talloc() .
  236: .SH RETURN VALUE
  237: .B pool_create()
  238: returns a pointer to
  239: .BR "struct alloc_pool" .
  240: .P
  241: .B pool_alloc()
  242: and
  243: .B pool_talloc()
  244: return pointers to the allocated memory,
  245: or NULL if the request fails.
  246: The return type of
  247: .B pool_alloc()
  248: will normally require casting to the desired type but
  249: .B pool_talloc()
  250: will returns a pointer of the requested
  251: .IR type .
  252: .P
  253: .B pool_boundary()
  254: returns a pointer that should only be used in a call to
  255: .BR pool_free_old() .
  256: .P
  257: .BR pool_free() ,
  258: .BR pool_free_old() ,
  259: .B pool_tfree()
  260: and
  261: .B pool_destroy()
  262: return no value.
  263: .SH SEE ALSO
  264: .nf
  265: malloc(3)
  266: .SH AUTHOR
  267: pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
  268: .SH BUGS AND ISSUES