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

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)

Boost C++ Libraries