# Pool

## Introduction

pool is a fast memory allocator, and guarantees proper alignment of all allocated chunks.

pool.hpp provides two UserAllocator classes and a template class pool, which extends and generalizes the framework provided by the simple segregated storage solution. For information on other pool-based interfaces, see the other pool interfaces.

## Synopsis

    struct default_user_allocator_new_delete; // see User Allocators
    struct default_user_allocator_malloc_free; // see User Allocators

    template <typename UserAllocator = default_user_allocator_new_delete>
    class pool
    {
      private:
        pool(const pool &);
        void operator=(const pool &);

      public:
        typedef UserAllocator user_allocator;
        typedef typename UserAllocator::size_type size_type;
        typedef typename UserAllocator::difference_type difference_type;

        explicit pool(size_type requested_size);
        ~pool();

        bool release_memory();
        bool purge_memory();

        bool is_from(void * chunk) const;
        size_type get_requested_size() const;

        void * malloc();
        void * ordered_malloc();
        void * ordered_malloc(size_type n);

        void free(void * chunk);
        void ordered_free(void * chunk);
        void free(void * chunks, size_type n);
        void ordered_free(void * chunks, size_type n);
    };

## Template Parameters

### UserAllocator

Defines the method that the Pool will use to allocate memory from the system. See User Allocators for details.

## Semantics

Symbol Table
Symbol | Meaning
--- | ---
Pool | pool<UserAllocator>
t | value of type Pool
u | value of type const Pool
chunk | value of type void *
n | value of type size_type
RequestedSize | value of type Pool::size_type; must be greater than 0

Typedefs
Expression | Type
--- | ---
Pool::user_allocator | UserAllocator
Pool::size_type | UserAllocator::size_type
Pool::difference_type | UserAllocator::difference_type

Constructors, Destructors, and Testing
Expression | Return Type | Notes
--- | --- | ---
Pool(RequestedSize) | not used | Constructs a new empty Pool that can be used to allocate chunks of size RequestedSize
(&t)->~Pool() | not used | Destructs the Pool, freeing its list of memory blocks
u.is_from(chunk) | bool | Returns true if chunk was allocated from u or may be returned as the result of a future allocation from u. Returns false if chunk was allocated from some other pool or may be returned as the result of a future allocation from some other pool. Otherwise, the return value is meaningless; note that this function may not be used to reliably test random pointer values.
u.get_requested_size() | size_type | Returns the value passed into the constructor. This value will not change during the lifetime of a Pool object.

Allocation and Deallocation
Expression | Return Type | Pre-Condition | Notes
--- | --- | --- | ---
t.malloc() | void * |  | Allocates a chunk of memory. Searches in the list of memory blocks for a block that has a free chunk, and returns that free chunk if found. Otherwise, creates a new memory block, adds its free list to t's free list, and returns a free chunk from that block. If a new memory block cannot be allocated, returns 0. Amortized O(1).
t.ordered_malloc() | void * |  | Same as above, only merges the free lists, to preserve order. Amortized O(1).
t.ordered_malloc(n) | void * |  | Same as above, only allocates enough contiguous chunks to cover n * requested_size bytes. Amortized O(n).
t.free(chunk) | void | chunk must have been previously returned by t.malloc() or t.ordered_malloc(). | Deallocates a chunk of memory. Note that chunk may not be 0. O(1).
t.ordered_free(chunk) | void | Same as above | Same as above, but is order-preserving. Note that chunk may not be 0. O(N) with respect to the size of the free list
t.free(chunk, n) | void | chunk must have been previously returned by t.ordered_malloc(n). | Assumes that chunk actually refers to a block of chunks spanning n * partition_sz bytes; deallocates each chunk in that block. Note that chunk may not be 0. O(n).
t.ordered_free(chunk, n) | void | chunk must have been previously returned by t.ordered_malloc(n). | Assumes that chunk actually refers to a block of chunks spanning n * partition_sz bytes; deallocates each chunk in that block. Note that chunk may not be 0. Order-preserving. O(N + n) where N is the size of the free list.
t.release_memory() | bool | t must be ordered. | Frees every memory block that doesn't have any allocated chunks. Returns true if at least one memory block was freed.
t.purge_memory() | bool |  | Frees every memory block. This function invalidates any pointers previously returned by allocation functions of t. Returns true if at least one memory block was freed.

## Symbols

- boost::default_user_allocator_new_delete
- boost::default_user_allocator_malloc_new
- boost::pool

## Implementation Details

Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

This file can be redistributed and/or modified under the terms found in copyright.html

This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.