### _upool -- Create a Memory Pool

Format

>     #include <umalloc.h>
>     int _upool(Heap_t uh, size_t min_size, size_t max_size,
>                size_t incr_qty, size_t flag);

Language Level: Extension
_upool creates a memory pool for objects that are allocated from the uh heap, and whose size fall between min_size and max_size.

Allocations from the pool are made in the usual way, using malloc and _umalloc. In this way, pooling is transparent. The only change you need to make to existing code is to add the _upool statement.

The runtime automatically creates a pool for the default runtime heap for sizes of 1 to 512 bytes with alignment of 8 and without _POOL_PRESERVE. To remove the default pool for the runtime heap, invoke _upool with the min_size and max_size parameters set to 0. It is essential that you perform this operation before allocating any objects.

Note: The default runtime heap is the only one that has pooling enabled by default. Unless you explicitly invoke _upool, any heap you create using _ucreate will not have a memory pool.

The incr_qty parameter is the number of items of a particular size that will be added to the pool when it is empty and needs to be expanded. This information is an optimization hint that may influence the incremental growth rate of the pool.

Note: Because the same incr_qty applies to all sizes of objects in the pool, you must choose the setting carefully. Large values may cause space to be reserved for items that will never be allocated.

You can set the following flags: _POOL_PRESERVE, and one from _ALIGN4, _ALIGN8 and _ALIGN16. Set _POOL_RESERVE to indicate that a heapmin operation on heap uh should not attempt to minimize the pool. The values _ALIGN4, _ALIGN8 and _ALIGN16 will align the returned objects from the pool on that particular boundary.

You can also choose to combine _POOL_RESERVE and _ALIGNx in the following manner:

> _POOL_RESERVE | _ALIGNx

If you do not set any flags, by specifying 0 for flags, then the defaults are _ALIGN8, and calls to _uheapmin will attempt to minimize the pool.

_upool is ideal to use for applications that allocate and free objects within a narrow range of sizes, and where heap operations account for a significant part of execution time. Because storage is reserved for objects of the specified sizes, and this storage is managed separately from the rest of the heap, allocation and frees will be significantly faster.

To remove a previously created pool for a heap, a call to _upool is made, with the min_size and max_size parameters set to 0. All storage within the pool will be returned back to the heap specified in the call. All objects in the pool must be freed first, before attempting to remove the pool. Otherwise, storage pages that contain any pool item are never returned to the heap, and the objects themselves can never be freed.

Return Value
If successful, _upool returns 0.

Example
In this example, _upool is invoked to create a transparent memory pool, and then _uflush is called to return all the storage to the heap.

    #include <stdlib.h>
    #include <stdio.h>
    #include <umalloc.h>

    int main(void)
    {
       char *p1, *p2;

       if (_upool(_RUNTIME_HEAP, 1, 128, 1000, _ALIGN8))
          printf ("Function _upool failed.\n");

       p1 = (char*)malloc(32);   /* allocation will be from pool */
       p2 = (char*)malloc(200);  /* allocation will not be from pool */
       free(p1);
       free(p2);

       if (_uflush(_RUNTIME_HEAP, 0)) /* flush the entire pool */
          printf ("Function _uflush failed.\n");

       return 0;
    }

_uflush -- Release Unused Memory from Memory Pool
_ustats -- Get Information about Heap
<stdlib.h>
<stdio.h>
<umalloc.h>