Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
C++ Boost

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

Implementation Details

Valid HTML 4.01 Transitional

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)