Return to pool_alloc.3 CVS log

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

rsync

    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