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
SymbolMeaning
Poolpool<UserAllocator>
tvalue of type Pool
uvalue of type const Pool
chunkvalue of type void *
nvalue of type size_type
RequestedSizevalue of type Pool::size_type; must be greater than 0

Typedefs
ExpressionType
Pool::user_allocatorUserAllocator
Pool::size_typeUserAllocator::size_type
Pool::difference_typeUserAllocator::difference_type

Constructors, Destructors, and Testing
ExpressionReturn TypeNotes
Pool(RequestedSize)not usedConstructs a new empty Pool that can be used to allocate chunks of size RequestedSize
(&t)->~Pool()not usedDestructs the Pool, freeing its list of memory blocks
u.is_from(chunk)boolReturns 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_typeReturns the value passed into the constructor. This value will not change during the lifetime of a Pool object.

Allocation and Deallocation
ExpressionReturn TypePre-ConditionNotes
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)voidchunk 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)voidSame as aboveSame 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)voidchunk 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)voidchunk 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()boolt 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()boolFrees 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


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.