# 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

Revised 05 December, 2006

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

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)