pool_alloc.hpp File Reference

C++ Standard Library compatible pool-based allocators. More...

#include <boost/limits.hpp>
#include <new>
#include <boost/throw_exception.hpp>
#include <boost/pool/poolfwd.hpp>
#include <boost/pool/singleton_pool.hpp>
#include <boost/detail/workaround.hpp>

Include dependency graph for pool_alloc.hpp:

This graph shows which files directly or indirectly include this file:

Classes
struct	boost::pool_allocator_tag
	Simple tag type used by pool_allocator as an argument to the underlying singleton_pool. More...
singleton	boost::pool_allocator< T, UserAllocator, Mutex, NextSize, MaxSize >
	A C++ Standard Library conforming allocator, based on an underlying pool. More...
struct	boost::pool_allocator< T, UserAllocator, Mutex, NextSize, MaxSize >::rebind< U >
	Nested class rebind allows for transformation from pool_allocator<T> to pool_allocator<U>. More...
class	boost::pool_allocator< void, UserAllocator, Mutex, NextSize, MaxSize >
	Specialization of pool_allocator<void>. More...
struct	boost::pool_allocator< void, UserAllocator, Mutex, NextSize, MaxSize >::rebind< U >
	Nested class rebind allows for transformation from pool_allocator<T> to pool_allocator<U>. More...
struct	boost::fast_pool_allocator_tag
	Simple tag type used by fast_pool_allocator as a template parameter to the underlying singleton_pool. More...
singleton	boost::fast_pool_allocator< T, UserAllocator, Mutex, NextSize, MaxSize >
	A C++ Standard Library conforming allocator geared towards allocating single chunks. More...
struct	boost::fast_pool_allocator< T, UserAllocator, Mutex, NextSize, MaxSize >::rebind< U >
	Nested class rebind allows for transformation from fast_pool_allocator<T> to fast_pool_allocator<U>. More...
class	boost::fast_pool_allocator< void, UserAllocator, Mutex, NextSize, MaxSize >
	Specialization of fast_pool_allocator<void>. More...
struct	boost::fast_pool_allocator< void, UserAllocator, Mutex, NextSize, MaxSize >::rebind< U >
	Nested class rebind allows for transformation from fast_pool_allocator<T> to fast_pool_allocator<U>. More...

Namespaces
	boost
	Duration formatting facet for input.

Detailed Description

C++ Standard Library compatible pool-based allocators.

This header provides two template types - pool_allocator and fast_pool_allocator - that can be used for fast and efficient memory allocation in conjunction with the C++ Standard Library containers.

These types both satisfy the Standard Allocator requirements [20.1.5] and the additional requirements in [20.1.5/4], so they can be used with either Standard or user-supplied containers.

In addition, the fast_pool_allocator also provides an additional allocation and an additional deallocation function:

Expression	Return Type	Semantic Equivalence
PoolAlloc::allocate()	T *	PoolAlloc::allocate(1)
PoolAlloc::deallocate(p)	void	PoolAlloc::deallocate(p, 1)

The typedef user_allocator publishes the value of the UserAllocator template parameter.

Notes

If the allocation functions run out of memory, they will throw std::bad_alloc.

The underlying Pool type used by the allocators is accessible through the Singleton Pool Interface. The identifying tag used for pool_allocator is pool_allocator_tag, and the tag used for fast_pool_allocator is fast_pool_allocator_tag. All template parameters of the allocators (including implementation-specific ones) determine the type of the underlying Pool, with the exception of the first parameter T, whose size is used instead.

Since the size of T is used to determine the type of the underlying Pool, each allocator for different types of the same size will share the same underlying pool. The tag class prevents pools from being shared between pool_allocator and fast_pool_allocator. For example, on a system where sizeof(int) == sizeof(void *), pool_allocator<int> and pool_allocator<void *> will both allocate/deallocate from/to the same pool.

If there is only one thread running before main() starts and after main() ends, then both allocators are completely thread-safe.

Compiler and STL Notes

A number of common STL libraries contain bugs in their using of allocators. Specifically, they pass null pointers to the deallocate function, which is explicitly forbidden by the Standard [20.1.5 Table 32]. PoolAlloc will work around these libraries if it detects them; currently, workarounds are in place for: Borland C++ (Builder and command-line compiler) with default (RogueWave) library, ver. 5 and earlier, STLport (with any compiler), ver. 4.0 and earlier.