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

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.