|
+Home | +Libraries | +People | +FAQ | +More | +
+BOOST_POOL_VALIDATE_INTERNALS
+// In header: <boost/pool/simple_segregated_storage.hpp>
+
+BOOST_POOL_VALIDATE_INTERNALS| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::default_user_allocator_malloc_free — UserAllocator used as template parameter for pool and object_pool. Uses malloc and free internally.
+// In header: <boost/pool/pool.hpp> + + +struct default_user_allocator_malloc_free { + // types + typedef std::size_t size_type; // An unsigned integral type that can represent the size of the largest object to be allocated. + typedef std::ptrdiff_t difference_type; // A signed integral type that can represent the difference of any two pointers. + + // public static functions + static char * malloc(const size_type); + static void free(char *const); +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::default_user_allocator_new_delete — Allocator used as the default template parameter for a UserAllocator template parameter. Uses new and delete.
+// In header: <boost/pool/pool.hpp> + + +struct default_user_allocator_new_delete { + // types + typedef std::size_t size_type; // An unsigned integral type that can represent the size of the largest object to be allocated. + typedef std::ptrdiff_t difference_type; // A signed integral type that can represent the difference of any two pointers. + + // public static functions + static char * malloc(const size_type); + static void free(char *const); +};
default_user_allocator_new_delete public static functionsstatic char * malloc(const size_type bytes);+
Attempts to allocate n bytes from the system. Returns 0 if out-of-memory
+static void free(char *const block);+
Attempts to de-allocate block. +
+Requires: |
+Block must have been previously returned from a call to UserAllocator::malloc. |
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::fast_pool_allocator — A C++ Standard Library conforming allocator geared towards allocating single chunks.
+// In header: <boost/pool/pool_alloc.hpp> + +template<typename T, typename UserAllocator, typename Mutex, + unsigned NextSize, unsigned MaxSize> +class fast_pool_allocator { +public: + // types + typedef T value_type; + typedef UserAllocator user_allocator; + typedef Mutex mutex; + typedef value_type * pointer; + typedef const value_type * const_pointer; + typedef value_type & reference; + typedef const value_type & const_reference; + typedef pool< UserAllocator >::size_type size_type; + typedef pool< UserAllocator >::difference_type difference_type; + + // member classes/structs/unions + + // Nested class rebind allows for transformation from fast_pool_allocator<T> + // to fast_pool_allocator<U>. + template<typename U> + struct rebind { + // types + typedef fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; + }; + + // construct/copy/destruct + fast_pool_allocator(); + template<typename U> + fast_pool_allocator(const fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > &); + + // public member functions + void construct(const pointer, const value_type &); + void destroy(const pointer); + bool operator==(const fast_pool_allocator &) const; + bool operator!=(const fast_pool_allocator &) const; + + // public static functions + static pointer address(reference); + static const_pointer address(const_reference); + static size_type max_size(); + static pointer allocate(const size_type); + static pointer allocate(const size_type, const void *); + static pointer allocate(); + static void deallocate(const pointer, const size_type); + static void deallocate(const pointer); + + // public data members + static const unsigned next_size; +};
While class template pool_allocator is a more general-purpose solution geared towards efficiently servicing requests for any number of contiguous chunks, fast_pool_allocator is also a general-purpose solution, but is geared towards efficiently servicing requests for one chunk at a time; it will work for contiguous chunks, but not as well as pool_allocator.
If you are seriously concerned about performance, use fast_pool_allocator when dealing with containers such as std::list, and use pool_allocator when dealing with containers such as std::vector.
The template parameters are defined as follows:
+T Type of object to allocate/deallocate.
+UserAllocator. Defines the method that the underlying Pool will use to allocate memory from the system. See User Allocators for details.
+Mutex Allows the user to determine the type of synchronization to be used on the underlying singleton_pool.
NextSize The value of this parameter is passed to the underlying Pool when it is created.
+MaxSize Limit on the maximum size used.
+![[Note]](../../../../../doc/src/images/note.png) |
+Note | +
|---|---|
The underlying singleton_pool used by the this allocator constructs a pool instance that is never freed. This means that memory allocated by the allocator can be still used after main() has completed, but may mean that some memory checking programs will complain about leaks. |
+
+fast_pool_allocator
+ public
+ construct/copy/destructfast_pool_allocator();+
Ensures construction of the underlying singleton_pool IFF an instance of this allocator is constructed during global initialization. See ticket #2359 for a complete explanation at http://svn.boost.org/trac/boost/ticket/2359 .
template<typename U> + fast_pool_allocator(const fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > &);+
Ensures construction of the underlying singleton_pool IFF an instance of this allocator is constructed during global initialization. See ticket #2359 for a complete explanation at http://svn.boost.org/trac/boost/ticket/2359 .
fast_pool_allocator public member functionsvoid construct(const pointer ptr, const value_type & t);
void destroy(const pointer ptr);+
Destroy ptr using destructor.
+bool operator==(const fast_pool_allocator &) const;
bool operator!=(const fast_pool_allocator &) const;
fast_pool_allocator public static functionsstatic pointer address(reference r);
static const_pointer address(const_reference s);
static size_type max_size();
static pointer allocate(const size_type n);
static pointer allocate(const size_type n, const void * const);+
Allocate memory .
+static pointer allocate();+
Allocate memory.
+static void deallocate(const pointer ptr, const size_type n);+
Deallocate memory.
+static void deallocate(const pointer ptr);+
deallocate/free
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::fast_pool_allocator::rebind — Nested class rebind allows for transformation from fast_pool_allocator<T> to fast_pool_allocator<U>.
+// In header: <boost/pool/pool_alloc.hpp> + + + +// Nested class rebind allows for transformation from fast_pool_allocator<T> +// to fast_pool_allocator<U>. +template<typename U> +struct rebind { + // types + typedef fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::fast_pool_allocator_tag — Simple tag type used by fast_pool_allocator as a template parameter to the underlying singleton_pool.
+// In header: <boost/pool/pool_alloc.hpp> + + +struct fast_pool_allocator_tag { +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize> — Specialization of fast_pool_allocator<void>.
+// In header: <boost/pool/pool_alloc.hpp> + +template<typename UserAllocator, typename Mutex, unsigned NextSize, + unsigned MaxSize> +class fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize> { +public: + // types + typedef void * pointer; + typedef const void * const_pointer; + typedef void value_type; + + // member classes/structs/unions + + // Nested class rebind allows for transformation from fast_pool_allocator<T> + // to fast_pool_allocator<U>. + template<typename U> + struct rebind { + // types + typedef fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; + }; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>::rebind — Nested class rebind allows for transformation from fast_pool_allocator<T> to fast_pool_allocator<U>.
+// In header: <boost/pool/pool_alloc.hpp> + + + +// Nested class rebind allows for transformation from fast_pool_allocator<T> +// to fast_pool_allocator<U>. +template<typename U> +struct rebind { + // types + typedef fast_pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::object_pool — A template class that can be used for fast and efficient memory allocation of objects. It also provides automatic destruction of non-deallocated objects.
+// In header: <boost/pool/object_pool.hpp> + +template<typename T, typename UserAllocator> +class object_pool : protected boost::pool< UserAllocator > { +public: + // types + typedef T element_type; // ElementType. + typedef UserAllocator user_allocator; // User allocator. + typedef pool< UserAllocator >::size_type size_type; // pool<UserAllocator>::size_type + typedef pool< UserAllocator >::difference_type difference_type; // pool<UserAllocator>::difference_type + + // construct/copy/destruct + explicit object_pool(const size_type = 32, const size_type = 0); + ~object_pool(); + + // protected member functions + pool< UserAllocator > & store(); + const pool< UserAllocator > & store() const; + + // protected static functions + static void *& nextof(void *const); + + // public member functions + element_type * malloc(); + void free(element_type *const); + bool is_from(element_type *const) const; + element_type * construct(); + template<typename Arg1, ...class ArgN> + element_type * construct(Arg1 &, ...ArgN &); + void destroy(element_type *const); + size_type get_next_size() const; + void set_next_size(const size_type); +};
T The type of object to allocate/deallocate. T must have a non-throwing destructor.
+UserAllocator Defines the allocator that the underlying Pool will use to allocate memory from the system. See User Allocators for details.
+Class object_pool is a template class that can be used for fast and efficient memory allocation of objects. It also provides automatic destruction of non-deallocated objects.
+When the object pool is destroyed, then the destructor for type T is called for each allocated T that has not yet been deallocated. O(N).
+Whenever an object of type ObjectPool needs memory from the system, it will request it from its UserAllocator template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled. Users may control the doubling algorithm by the parameters passed to the object_pool's constructor.
+ + + +object_pool public member functionselement_type * malloc();+
Allocates memory that can hold one object of type ElementType.
+If out of memory, returns 0.
+Amortized O(1).
+void free(element_type *const chunk);+
De-Allocates memory that holds a chunk of type ElementType.
+Note that p may not be 0.
+
Note that the destructor for p is not called. O(N).
+bool is_from(element_type *const chunk) const;+
+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 | +
|---|---|
This function may NOT be used to reliably test random pointer values! |
+
+Returns: |
+true if chunk was allocated from *this or may be returned as the result of a future allocation from *this. |
+
element_type * construct();+
+
+Returns: |
+A pointer to an object of type T, allocated in memory from the underlying pool and default constructed. The returned objected can be freed by a call to destroy. Otherwise the returned object will be automatically destroyed when *this is destroyed. |
+
template<typename Arg1, ...class ArgN> + element_type * construct(Arg1 &, ...ArgN &);+
+
+ |
+Note | +
|---|---|
Since the number and type of arguments to this function is totally arbitrary, a simple system has been set up to automatically generate template construct functions. This system is based on the macro preprocessor m4, which is standard on UNIX systems and also available for Win32 systems. |
+
+Returns: |
+A pointer to an object of type T, allocated in memory from the underlying pool and constructed from arguments Arg1 to ArgN. The returned objected can be freed by a call to destroy. Otherwise the returned object will be automatically destroyed when *this is destroyed. |
+
void destroy(element_type *const chunk);+
Destroys an object allocated with construct.
+Equivalent to:
+p->~ElementType(); this->free(p);
++
+Requires: |
+p must have been previously allocated from *this via a call to construct. |
+
size_type get_next_size() const;+
+
+Returns: |
+The number of chunks that will be allocated next time we run out of memory. |
+
void set_next_size(const size_type x);+
Set a new number of chunks to allocate the next time we run out of memory. +
+Parameters: |
+
|
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool — A fast memory allocator that guarantees proper alignment of all allocated chunks.
+// In header: <boost/pool/pool.hpp> + +template<typename UserAllocator> +class pool : + protected boost::simple_segregated_storage< UserAllocator::size_type > +{ +public: + // types + typedef UserAllocator user_allocator; // User allocator. + typedef UserAllocator::size_type size_type; // An unsigned integral type that can represent the size of the largest object to be allocated. + typedef UserAllocator::difference_type difference_type; // A signed integral type that can represent the difference of any two pointers. + + // construct/copy/destruct + explicit pool(const size_type, const size_type = 32, const size_type = 0); + ~pool(); + + // private member functions + void * malloc_need_resize(); + void * ordered_malloc_need_resize(); + + // protected member functions + simple_segregated_storage< size_type > & store(); + const simple_segregated_storage< size_type > & store() const; + details::PODptr< size_type > find_POD(void *const) const; + size_type alloc_size() const; + + // protected static functions + static bool is_from(void *const, char *const, const size_type); + static void *& nextof(void *const); + + // public member functions + bool release_memory(); + bool purge_memory(); + size_type get_next_size() const; + void set_next_size(const size_type); + size_type get_max_size() const; + void set_max_size(const size_type); + size_type get_requested_size() const; + void * malloc(); + void * ordered_malloc(); + void * ordered_malloc(size_type); + void free(void *const); + void ordered_free(void *const); + void free(void *const, const size_type); + void ordered_free(void *const, const size_type); + bool is_from(void *const) const; +};
Whenever an object of type pool needs memory from the system, it will request it from its UserAllocator template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled.
+Users may control the doubling algorithm by using the following extensions:
+Users may pass an additional constructor parameter to pool. This parameter is of type size_type, and is the number of chunks to request from the system the first time that object needs to allocate system memory. The default is 32. This parameter may not be 0.
+Users may also pass an optional third parameter to pool's constructor. This parameter is of type size_type, and sets a maximum size for allocated chunks. When this parameter takes the default value of 0, then there is no upper limit on chunk size.
+Finally, if the doubling algorithm results in no memory being allocated, the pool will backtrack just once, halving the chunk size and trying again.
+UserAllocator type - the method that the Pool will use to allocate memory from the system.
+There are essentially two ways to use class pool: the client can call malloc() and free() to allocate and free single chunks of memory, this is the most efficient way to use a pool, but does not allow for the efficient allocation of arrays of chunks. Alternatively, the client may call ordered_malloc() and ordered_free(), in which case the free list is maintained in an ordered state, and efficient allocation of arrays of chunks are possible. However, this latter option can suffer from poor performance when large numbers of allocations are performed.
+pool
+ public
+ construct/copy/destructexplicit pool(const size_type nrequested_size, + const size_type nnext_size = 32, const size_type nmax_size = 0);+
Constructs a new empty Pool that can be used to allocate chunks of size RequestedSize. +
+Parameters: |
+
|
+
~pool();+
Destructs the Pool, freeing its list of memory blocks.
+pool private member functionsvoid * malloc_need_resize();+
+
+No memory in any of our storages; make a new storage, Allocates chunk in newly malloc aftert resize. +
+Returns: |
+0 if out-of-memory. Called if malloc/ordered_malloc needs to resize the free list. |
+
Returns: |
+pointer to chunk. |
+
void * ordered_malloc_need_resize();Called if malloc needs to resize the free list.
No memory in any of our storages; make a new storage, +
+Returns: |
+pointer to new chunk. |
+
pool protected member functionssimple_segregated_storage< size_type > & store();+
+
+Returns: |
+pointer to store. |
+
const simple_segregated_storage< size_type > & store() const;+
+
+Returns: |
+pointer to store. |
+
details::PODptr< size_type > find_POD(void *const chunk) const;finds which POD in the list 'chunk' was allocated from.
find which PODptr storage memory that this chunk is from. +
+Returns: |
+the PODptr that holds this chunk. |
+
size_type alloc_size() const;+
Calculated size of the memory chunks that will be allocated by this Pool. +
+Returns: |
+allocated size. |
+
pool protected static functionsstatic bool is_from(void *const chunk, char *const i, + const size_type sizeof_i);+
+ +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.
+Parameters: |
+
|
+||||||
Returns: |
+true if chunk was allocated or may be returned. as the result of a future allocation. |
+
static void *& nextof(void *const ptr);+
+
+Returns: |
+Pointer dereferenced. (Provided and used for the sake of code readability :) |
+
pool public member functionsbool release_memory();+
pool must be ordered. Frees every memory block that doesn't have any allocated chunks. +
+Returns: |
+true if at least one memory block was freed. |
+
bool purge_memory();+
pool must be ordered. 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. |
+
size_type get_next_size() const;+
Number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be 0. +
+Returns: |
+next_size; |
+
void set_next_size(const size_type nnext_size);+
Set number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be set to 0. +
+Returns: |
+nnext_size. |
+
size_type get_max_size() const;+
+
+Returns: |
+max_size. |
+
void set_max_size(const size_type nmax_size);+
Set max_size.
+size_type get_requested_size() const;+
+
+Returns: |
+the requested size passed into the constructor. (This value will not change during the lifetime of a Pool object). |
+
void * malloc();+
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 pool's free list, +
+Returns: |
+a free chunk from that block. If a new memory block cannot be allocated, returns 0. Amortized O(1). |
+
void * ordered_malloc();+
Same as malloc, only merges the free lists, to preserve order. Amortized O(1). +
+Returns: |
+a free chunk from that block. If a new memory block cannot be allocated, returns 0. Amortized O(1). |
+
void * ordered_malloc(size_type n);+
Gets address of a chunk n, allocating new memory if not already available. +
+Returns: |
+
+ Address of chunk n if allocated ok. +0 if not enough memory for n chunks. + |
+
void free(void *const chunk);+
Same as malloc, only allocates enough contiguous chunks to cover n * requested_size bytes. Amortized O(n). +
+Deallocates a chunk of memory. Note that chunk may not be 0. O(1).
+Chunk must have been previously returned by t.malloc() or t.ordered_malloc(). 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).
+Returns: |
+a free chunk from that block. If a new memory block cannot be allocated, returns 0. Amortized O(1). |
+
void ordered_free(void *const chunk);+
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. chunk must have been previously returned by t.malloc() or t.ordered_malloc().
+void free(void *const chunks, const size_type n);+
Assumes that chunk actually refers to a block of chunks.
+chunk must have been previously returned by t.ordered_malloc(n) spanning n * partition_sz bytes. Deallocates each chunk in that block. Note that chunk may not be 0. O(n).
+void ordered_free(void *const chunks, const size_type 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. chunk must have been previously returned by t.malloc() or t.ordered_malloc().
+bool is_from(void *const chunk) const;+
+
+Returns: |
+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. |
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool_allocator — A C++ Standard Library conforming allocator, based on an underlying pool.
+// In header: <boost/pool/pool_alloc.hpp> + +template<typename T, typename UserAllocator, typename Mutex, + unsigned NextSize, unsigned MaxSize> +class pool_allocator { +public: + // types + typedef T value_type; // value_type of template parameter T. + typedef UserAllocator user_allocator; // allocator that defines the method that the underlying Pool will use to allocate memory from the system. + typedef Mutex mutex; // typedef mutex publishes the value of the template parameter Mutex. + typedef value_type * pointer; + typedef const value_type * const_pointer; + typedef value_type & reference; + typedef const value_type & const_reference; + typedef pool< UserAllocator >::size_type size_type; + typedef pool< UserAllocator >::difference_type difference_type; + + // member classes/structs/unions + + // Nested class rebind allows for transformation from pool_allocator<T> to + // pool_allocator<U>. + template<typename U> + struct rebind { + // types + typedef pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; + }; + + // construct/copy/destruct + pool_allocator(); + template<typename U> + pool_allocator(const pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > &); + + // public member functions + bool operator==(const pool_allocator &) const; + bool operator!=(const pool_allocator &) const; + + // public static functions + static pointer address(reference); + static const_pointer address(const_reference); + static size_type max_size(); + static void construct(const pointer, const value_type &); + static void destroy(const pointer); + static pointer allocate(const size_type); + static pointer allocate(const size_type, const void *); + static void deallocate(const pointer, const size_type); + + // public data members + static const unsigned next_size; // next_size publishes the values of the template parameter NextSize. +};
Template parameters for pool_allocator are defined as follows:
+T Type of object to allocate/deallocate.
+UserAllocator. Defines the method that the underlying Pool will use to allocate memory from the system. See User Allocators for details.
+Mutex Allows the user to determine the type of synchronization to be used on the underlying singleton_pool.
+NextSize The value of this parameter is passed to the underlying singleton_pool when it is created.
+MaxSize Limit on the maximum size used.
+ |
+Note | +
|---|---|
The underlying singleton_pool used by the this allocator constructs a pool instance that is never freed. This means that memory allocated by the allocator can be still used after main() has completed, but may mean that some memory checking programs will complain about leaks. |
+
+pool_allocator
+ public
+ construct/copy/destructpool_allocator();+
Results in default construction of the underlying singleton_pool IFF an instance of this allocator is constructed during global initialization ( required to ensure construction of singleton_pool IFF an instance of this allocator is constructed during global initialization. See ticket #2359 for a complete explanation at http://svn.boost.org/trac/boost/ticket/2359) .
template<typename U> + pool_allocator(const pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > &);+
Results in the default construction of the underlying singleton_pool, this is required to ensure construction of singleton_pool IFF an instance of this allocator is constructed during global initialization. See ticket #2359 for a complete explanation at http://svn.boost.org/trac/boost/ticket/2359 .
pool_allocator public member functionsbool operator==(const pool_allocator &) const;
bool operator!=(const pool_allocator &) const;
pool_allocator public static functionsstatic pointer address(reference r);
static const_pointer address(const_reference s);
static size_type max_size();
static void construct(const pointer ptr, const value_type & t);
static void destroy(const pointer ptr);
static pointer allocate(const size_type n);
static pointer allocate(const size_type n, const void * const);+
allocate n bytes
++
+Parameters: |
+
|
+
static void deallocate(const pointer ptr, const size_type n);+
Deallocate n bytes from ptr +
+Parameters: |
+
|
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool_allocator::rebind — Nested class rebind allows for transformation from pool_allocator<T> to pool_allocator<U>.
+// In header: <boost/pool/pool_alloc.hpp> + + + +// Nested class rebind allows for transformation from pool_allocator<T> to +// pool_allocator<U>. +template<typename U> +struct rebind { + // types + typedef pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool_allocator_tag
+// In header: <boost/pool/pool_alloc.hpp> + + +struct pool_allocator_tag { +};
Simple tag type used by pool_allocator as an argument to the underlying singleton_pool.
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize> — Specialization of pool_allocator<void>.
+// In header: <boost/pool/pool_alloc.hpp> + +template<typename UserAllocator, typename Mutex, unsigned NextSize, + unsigned MaxSize> +class pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize> { +public: + // types + typedef void * pointer; + typedef const void * const_pointer; + typedef void value_type; + + // member classes/structs/unions + + // Nested class rebind allows for transformation from pool_allocator<T> to + // pool_allocator<U>. + template<typename U> + struct rebind { + // types + typedef pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; + }; +};
Specialization of pool_allocator for type void: required by the standard to make this a conforming allocator type.
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>::rebind — Nested class rebind allows for transformation from pool_allocator<T> to pool_allocator<U>.
+// In header: <boost/pool/pool_alloc.hpp> + + + +// Nested class rebind allows for transformation from pool_allocator<T> to +// pool_allocator<U>. +template<typename U> +struct rebind { + // types + typedef pool_allocator< U, UserAllocator, Mutex, NextSize, MaxSize > other; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::simple_segregated_storage — Simple Segregated Storage is the simplest, and probably the fastest, memory allocation/deallocation algorithm. It is responsible for partitioning a memory block into fixed-size chunks: where the block comes from is determined by the client of the class.
+// In header: <boost/pool/simple_segregated_storage.hpp> + +template<typename SizeType> +class simple_segregated_storage { +public: + // types + typedef SizeType size_type; + + // construct/copy/destruct + simple_segregated_storage(const simple_segregated_storage &); + simple_segregated_storage(); + simple_segregated_storage& operator=(const simple_segregated_storage &); + + // private static functions + static void * try_malloc_n(void *&, size_type, size_type); + + // protected member functions + void * find_prev(void *); + + // protected static functions + static void *& nextof(void *const); + + // public member functions + void add_block(void *const, const size_type, const size_type); + void add_ordered_block(void *const, const size_type, const size_type); + bool empty() const; + void * malloc(); + void free(void *const); + void ordered_free(void *const); + void * malloc_n(size_type, size_type); + void free_n(void *const, const size_type, const size_type); + void ordered_free_n(void *const, const size_type, const size_type); + + // public static functions + static void * segregate(void *, size_type, size_type, void * = 0); +};
Template class simple_segregated_storage controls access to a free list of memory chunks. Please note that this is a very simple class, with preconditions on almost all its functions. It is intended to be the fastest and smallest possible quick memory allocator - e.g., something to use in embedded systems. This class delegates many difficult preconditions to the user (i.e., alignment issues).
+An object of type simple_segregated_storage<SizeType> is empty if its free list is empty. If it is not empty, then it is ordered if its free list is ordered. A free list is ordered if repeated calls to malloc() will result in a constantly-increasing sequence of values, as determined by std::less<void *>. A member function is order-preserving if the free list maintains its order orientation (that is, an ordered free list is still ordered after the member function call).
simple_segregated_storage
+ public
+ construct/copy/destructsimple_segregated_storage(const simple_segregated_storage &);
simple_segregated_storage();+
Construct empty storage area. +
+Postconditions: |
+empty() |
+
simple_segregated_storage& operator=(const simple_segregated_storage &);
simple_segregated_storage private static functionsstatic void * +try_malloc_n(void *& start, size_type n, size_type partition_size);+
+ +
+Requires: |
+(n > 0), (start != 0), (nextof(start) != 0) |
+
Postconditions: |
+(start != 0) The function attempts to find n contiguous chunks of size partition_size in the free list, starting at start. If it succeds, it returns the last chunk in that contiguous sequence, so that the sequence is known by [start, {retval}] If it fails, it does do either because it's at the end of the free list or hits a non-contiguous chunk. In either case, it will return 0, and set start to the last considered chunk. You are at the end of the free list if nextof(start) == 0. Otherwise, start points to the last chunk in the contiguous sequence, and nextof(start) points to the first chunk in the next contiguous sequence (assuming an ordered free list). |
+
simple_segregated_storage protected member functionsvoid * find_prev(void * ptr);+
Traverses the free list referred to by "first", and returns the iterator previous to where "ptr" would go if it was in the free list. Returns 0 if "ptr" would go at the beginning of the free list (i.e., before "first").
+ |
+Note | +
|---|---|
Note that this function finds the location previous to where ptr would go if it was in the free list. It does not find the entry in the free list before ptr (unless ptr is already in the free list). Specifically, find_prev(0) will return 0, not the last entry in the free list. |
+ +
+Returns: |
+location previous to where ptr would go if it was in the free list. |
+
simple_segregated_storage protected static functionsstatic void *& nextof(void *const ptr);+
The return value is just *ptr cast to the appropriate type. ptr must not be 0. (For the sake of code readability :)
+As an example, let us assume that we want to truncate the free list after the first chunk. That is, we want to set *first to 0; this will result in a free list with only one entry. The normal way to do this is to first cast first to a pointer to a pointer to void, and then dereference and assign (*static_cast<void **>(first) = 0;). This can be done more easily through the use of this convenience function (nextof(first) = 0;). +
+Returns: |
+dereferenced pointer. |
+
simple_segregated_storage public member functionsvoid add_block(void *const block, const size_type nsz, + const size_type npartition_sz);+
Add block Segregate this block and merge its free list into the free list referred to by "first". + +
+Requires: |
+Same as segregate. |
+
Postconditions: |
+!empty() |
+
void add_ordered_block(void *const block, const size_type nsz, + const size_type npartition_sz);+
add block (ordered into list) This (slower) version of add_block segregates the block and merges its free list into our free list in the proper order.
+bool empty() const;+
+
+Returns: |
+true only if simple_segregated_storage is empty. |
+
void * malloc();+
Create a chunk. +
+Requires: |
+!empty() Increment the "first" pointer to point to the next chunk. |
+
void free(void *const chunk);+
Free a chunk. + +
+Requires: |
+chunk was previously returned from a malloc() referring to the same free list. |
+
Postconditions: |
+!empty() |
+
void ordered_free(void *const chunk);+
This (slower) implementation of 'free' places the memory back in the list in its proper order. + +
+Requires: |
+chunk was previously returned from a malloc() referring to the same free list |
+
Postconditions: |
+!empty(). |
+
void * malloc_n(size_type n, size_type partition_size);+
Attempts to find a contiguous sequence of n partition_sz-sized chunks. If found, removes them all from the free list and returns a pointer to the first. If not found, returns 0. It is strongly recommended (but not required) that the free list be ordered, as this algorithm will fail to find a contiguous sequence unless it is contiguous in the free list as well. Order-preserving. O(N) with respect to the size of the free list.
+void free_n(void *const chunks, const size_type n, + const size_type partition_size);+
+ +
+ |
+Note | +
|---|---|
If you're allocating/deallocating n a lot, you should be using an ordered pool. |
+
+Requires: |
+chunks was previously allocated from *this with the same values for n and partition_size. |
+
Postconditions: |
+!empty() |
+
void ordered_free_n(void *const chunks, const size_type n, + const size_type partition_size);+
Free n chunks from order list. +
+Requires: |
+
+ chunks was previously allocated from *this with the same values for n and partition_size. +n should not be zero (n == 0 has no effect). + |
+
simple_segregated_storage public static functionsstatic void * +segregate(void * block, size_type nsz, size_type npartition_sz, + void * end = 0);+
Segregate block into chunks. +
+Requires: |
+
+ npartition_sz >= sizeof(void *) +npartition_sz = sizeof(void *) * i, for some integer i +nsz >= npartition_sz +Block is properly aligned for an array of object of size npartition_sz and array of void *. The requirements above guarantee that any pointer to a chunk (which is a pointer to an element in an array of npartition_sz) may be cast to void **. + |
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::singleton_pool
+// In header: <boost/pool/singleton_pool.hpp> + +template<typename Tag, unsigned RequestedSize, typename UserAllocator, + typename Mutex, unsigned NextSize, unsigned MaxSize> +class singleton_pool { +public: + // types + typedef Tag tag; + typedef Mutex mutex; // The type of mutex used to synchonise access to this pool (defaultdetails::pool::default_mutex). + typedef UserAllocator user_allocator; // The user-allocator used by this pool, default =default_user_allocator_new_delete. + typedef pool< UserAllocator >::size_type size_type; // size_type of user allocator. + typedef pool< UserAllocator >::difference_type difference_type; // difference_type of user allocator. + + // member classes/structs/unions + + struct object_creator { + // construct/copy/destruct + object_creator(); + + // public member functions + void do_nothing() const; + }; + + // construct/copy/destruct + singleton_pool(); + + // public static functions + static void * malloc(); + static void * ordered_malloc(); + static void * ordered_malloc(const size_type); + static bool is_from(void *const); + static void free(void *const); + static void ordered_free(void *const); + static void free(void *const, const size_type); + static void ordered_free(void *const, const size_type); + static bool release_memory(); + static bool purge_memory(); + + // private static functions + static pool_type & get_pool(); + + // public data members + static const unsigned requested_size; // The size of each chunk allocated by this pool. + static const unsigned next_size; // The number of chunks to allocate on the first allocation. + static pool< UserAllocator > p; // For exposition only! +};
The singleton_pool class allows other pool interfaces for types of the same size to share the same pool. Template parameters are as follows:
+Tag User-specified type to uniquely identify this pool: allows different unbounded sets of singleton pools to exist.
+RequestedSize The size of each chunk returned by member function malloc().
UserAllocator User allocator, default = default_user_allocator_new_delete.
+Mutex This class is the type of mutex to use to protect simultaneous access to the underlying Pool. Can be any Boost.Thread Mutex type or boost::details::pool::null_mutex. It is exposed so that users may declare some singleton pools normally (i.e., with synchronization), but some singleton pools without synchronization (by specifying boost::details::pool::null_mutex) for efficiency reasons. The member typedef mutex exposes the value of this template parameter. The default for this parameter is boost::details::pool::default_mutex which is a synonym for either boost::details::pool::null_mutex (when threading support is turned off in the compiler (so BOOST_HAS_THREADS is not set), or threading support has ben explicitly disabled with BOOST_DISABLE_THREADS (Boost-wide disabling of threads) or BOOST_POOL_NO_MT (this library only)) or for boost::mutex (when threading support is enabled in the compiler).
NextSize The value of this parameter is passed to the underlying Pool when it is created and specifies the number of chunks to allocate in the first allocation request (defaults to 32). The member typedef static const value next_size exposes the value of this template parameter.
MaxSizeThe value of this parameter is passed to the underlying Pool when it is created and specifies the maximum number of chunks to allocate in any single allocation request (defaults to 0).
+Notes:
+The underlying pool p referenced by the static functions in singleton_pool is actually declared in a way that is:
+1 Thread-safe if there is only one thread running before main() begins and after main() ends -- all of the static functions of singleton_pool synchronize their access to p.
+2 Guaranteed to be constructed before it is used -- thus, the simple static object in the synopsis above would actually be an incorrect implementation. The actual implementation to guarantee this is considerably more complicated.
+3 Note too that a different underlying pool p exists for each different set of template parameters, including implementation-specific ones.
+4 The underlying pool is constructed "as if" by:
+pool<UserAllocator> p(RequestedSize, NextSize, MaxSize);
+ |
+Note | +
|---|---|
The underlying pool constructed by the singleton is never freed. This means that memory allocated by a singleton_pool can be still used after main() has completed, but may mean that some memory checking programs will complain about leaks from singleton_pool. |
+
+singleton_pool
+ public
+ typesThe Tag template parameter uniquely identifies this pool and allows different unbounded sets of singleton pools to exist. For example, the pool allocators use two tag classes to ensure that the two different allocator types never share the same underlying singleton pool. Tag is never actually used by singleton_pool.
+singleton_pool public static functionsstatic void * malloc();+
Equivalent to SingletonPool::p.malloc(); synchronized.
+static void * ordered_malloc();+
Equivalent to SingletonPool::p.ordered_malloc(); synchronized.
+static void * ordered_malloc(const size_type n);+
Equivalent to SingletonPool::p.ordered_malloc(n); synchronized.
+static bool is_from(void *const ptr);+
Equivalent to SingletonPool::p.is_from(chunk); synchronized. +
+Returns: |
+true if chunk is from SingletonPool::is_from(chunk) |
+
static void free(void *const ptr);+
Equivalent to SingletonPool::p.free(chunk); synchronized.
+static void ordered_free(void *const ptr);+
Equivalent to SingletonPool::p.ordered_free(chunk); synchronized.
+static void free(void *const ptr, const size_type n);+
Equivalent to SingletonPool::p.free(chunk, n); synchronized.
+static void ordered_free(void *const ptr, const size_type n);+
Equivalent to SingletonPool::p.ordered_free(chunk, n); synchronized.
+static bool release_memory();+
Equivalent to SingletonPool::p.release_memory(); synchronized.
+static bool purge_memory();+
Equivalent to SingletonPool::p.purge_memory(); synchronized.
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+boost::singleton_pool::object_creator
+// In header: <boost/pool/singleton_pool.hpp> + + + +struct object_creator { + // construct/copy/destruct + object_creator(); + + // public member functions + void do_nothing() const; +};
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Many, many thanks to the Boost peers, notably Jeff Garland, Beman Dawes, + Ed Brey, Gary Powell, Peter Dimov, and Jens Maurer for providing helpful + suggestions! +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Using Pools gives you more control over how memory is used in your program. + For example, you could have a situation where you want to allocate a bunch + of small objects at one point, and then reach a point in your program where + none of them are needed any more. Using pool interfaces, you can choose to + run their destructors or just drop them off into oblivion; the pool interface + will guarantee that there are no system memory leaks. +
++ Pools are generally used when there is a lot of allocation and deallocation + of small objects. Another common usage is the situation above, where many + objects may be dropped out of memory. +
++ In general, use Pools when you need a more efficient way to do unusual memory + control. +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Documentation and testing revision +
++ Features: +
+
+ This used Opera 11.0, and html_to_quickbook.css as
+ a special display format. On the Opera full taskbar (chose enable
+ full taskbar) View, Style, Manage modes, Display.
+
+ Choose add \boost-sandbox\boost_docs\trunk\doc\style\html\conversion\html_to_quickbook.css
+ to My Style Sheet. Html pages are now displayed as Quickbook and can be copied
+ and pasted into quickbook files using your favored text editor for Quickbook.
+
+ First release +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Pool allocators are found in many programming languages, and in many variations. + The beginnings of many implementations may be found in common programming + literature; some of these are given below. Note that none of these are complete + implementations of a Pool; most of these leave some aspects of a Pool as + a user exercise. However, in each case, even though some aspects are missing, + these examples use the same underlying concept of a Simple Segregated Storage + described in this document. +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+
+ See folder boost/libs/pool/test/.
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Report and view bugs and features by adding a ticket at Boost.Trac. +
++ Existing open tickets for this library alone can be viewed here. + Existing tickets for this library - including closed ones - can be viewed + here. +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Another pool interface will be written: a base class for per-class pool allocation. +
++ This "pool_base" interface will be Singleton Usage with Exceptions, + and built on the singleton_pool interface. +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+address
+ +add_block
+ +add_ordered_block
+ +allocate
+ +deallocate
+ +destroy
+ +find_prev
+ +free
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
free_n
+ +get_pool
+ +is_from
+ +main
+ +malloc
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
malloc_n
+ +malloc_need_resize
+ +max_size
+ +ordered_free
+ +ordered_free_n
+ +ordered_malloc
+ +ordered_malloc_need_resize
+ +purge_memory
+ +release_memory
+ +segregate
+ +set_max_size
+ +set_next_size
+ +sizeof
+ +try_malloc_n
+ +| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+default_user_allocator_malloc_free
+ +default_user_allocator_new_delete
+ +fast_pool_allocator
+ +fast_pool_allocator_tag
+ +object_creator
+ +object_pool
+ +pool
+ +pool_allocator
+ +pool_allocator_tag
+ +simple_segregated_storage
+ +singleton_pool
+ +| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+const_pointer
+ +const_reference
+ +difference_type
+ +element_type
+ +reference
+ +size_type
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
tag
+ +| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+A B C D E F G H I J M N O P R S T U V
+address
+ +add_block
+ +add_ordered_block
+ +alignment
+ +allocate
+ +allocation
+Boost Pool Interfaces - What interfaces are provided and when to use each one.
Guaranteeing Alignment - How we guarantee alignment portably.
Allocation and Deallocation
+Appendix B: FAQ
+Appendix F: Other Implementations
+Appendix G: References
+Appendix H: Future plans
+ +automatic
+ +Basic ideas behind pooling
+ +block
+ +Boost Pool Interfaces - What interfaces are provided and when to use each one.
+ +BOOST_POOL_VALIDATE_INTERNALS
+ +build
+ +Building the Test Programs
+ +chunk
+ +Class template fast_pool_allocator
+ +Class template fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>
+ +Class template object_pool
+Class template pool
+Class template pool_allocator
+ +Class template pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>
+ +Class template simple_segregated_storage
+ +Class template singleton_pool
+ +concepts
+ +construct
+ +Constructors, Destructors, and State
+ +const_pointer
+ +const_reference
+ +conventions
+ +deallocate
+ +deallocation
+ +default_user_allocator_malloc_free
+ +default_user_allocator_new_delete
+ +destroy
+ +difference_type
+ +Documentation Naming and Formatting Conventions
+ +elements
+ +element_type
+ +fast_pool_allocator
+ +fast_pool_allocator_tag
+ +find_prev
+ +free
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
free_n
+ +Header < boost/pool/object_pool.hpp >
+Header < boost/pool/pool.hpp >
+ +Header < boost/pool/poolfwd.hpp >
+ +Header < boost/pool/pool_alloc.hpp >
+Header < boost/pool/simple_segregated_storage.hpp >
+ +Header < boost/pool/singleton_pool.hpp >
+ +headers
+Class template fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>
Class template pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>
How Contiguous Chunks are Handled
+ +How do I use Pool?
+ +include
+ +Installation
+interface
+ +Introduction
+Introduction and Overview
+ +is_from
+ +jamfile
+ +Macro BOOST_POOL_VALIDATE_INTERNALS
+ +main
+ +malloc
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
malloc_n
+ +malloc_need_resize
+ +max_size
+ +memory
+ +mutex
+ +naming
+ +new
+ +nextof
+ +objects
+Boost Pool Interfaces - What interfaces are provided and when to use each one.
Guaranteeing Alignment - How we guarantee alignment portably.
Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
object_creator
+ +Object_pool
+ +object_pool
+ +ordered
+ +ordered_free
+ +ordered_free_n
+ +ordered_malloc
+ +ordered_malloc_need_resize
+ +other
+ +overview
+ +padding
+ +pointer
+ +pool
+Pool Interfaces
+ +pool_allocator
+Class template pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>
pool_allocator_tag
+ +portable
+ +purge_memory
+ +rebind
+ +reference
+ +release_memory
+ +segregate
+ +segregated
+ +Segregation
+ +set_max_size
+ +set_next_size
+ +Simple Segregated Storage
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
+ +simple_segregated_storage
+ +singleton
+Boost Pool Interfaces - What interfaces are provided and when to use each one.
Singleton_pool
+singleton_pool
+ +size
+Guaranteeing Alignment - How we guarantee alignment portably.
Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
sizeof
+ +size_type
+Simple Segregated Storage (Not for the faint of heart - Embedded programmers only!)
Struct default_user_allocator_malloc_free
+ +Struct default_user_allocator_new_delete
+ +Struct fast_pool_allocator_tag
+ +Struct object_creator
+ +Struct pool_allocator_tag
+ +Struct template rebind
+ +Symbol Table
+tag
+ +template
+ +Template Parameters
+ +try_malloc_n
+ +Typedefs
+ +UserAllocator Concept
+ +UserAllocator Requirements
+ +user_allocator
+ +| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ This documentation makes use of the following naming and formatting conventions. +
+fixed width
+ font and is syntax-highlighted
+ in color.
+ italics.
+ code
+ font followed by (), as in free_function().
+ class_template<>;
+ that is, it is in code font and its name is followed by <> to indicate that it is a class
+ template.
+ MACRO();
+ that is, it is uppercase in code font and its name is followed by () to indicate that it is a function-like
+ macro. Object-like macros appear without the trailing ().
+ ![[Note]](../../../../../../doc/src/images/note.png) |
+Note | +
|---|---|
+ In addition, notes such as this one specify non-essential information that + provides additional background or rationale. + |
+ Finally, you can mentally add the following to any code fragments in this + document: +
+// Include all of Pool files +#include <boost/pool.hpp> ++
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ The Boost Pool library is a header-only library. That means there is no .lib, + .dll, or .so to build; just add the Boost directory to your compiler's include + file path, and you should be good to go! +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ There are several interfaces provided which allow users great flexibility + in how they want to use Pools. Review the concepts + document to get the basic understanding of how the various pools work. +
++ Object Usage is the method where each Pool is an object that may be created + and destroyed. Destroying a Pool implicitly frees all chunks that have been + allocated from it. +
++ Singleton Usage is the method where each Pool is an object with static duration; + that is, it will not be destroyed until program exit. Pool objects with Singleton + Usage may be shared; thus, Singleton Usage implies thread-safety as well. + System memory allocated by Pool objects with Singleton Usage may be freed + through release_memory or purge_memory. +
+
+ Some Pool interfaces throw exceptions when out-of-memory; others will return 0. In
+ general, unless mandated by the Standard, Pool interfaces will always prefer
+ to return 0
+ instead of throwing an exception.
+
+ An ordered pool maintains it's free list in order of the address of each + free block - this is the most efficient way if you're likely to allocate + arrays of objects. However, freeing an object can be O(N) in the number of + currently free blocks which can be prohibitively expensive in some situations. +
++ An unordered pool does not maintain it's free list in any particular order, + as a result allocation and freeing single objects is very fast, but allocating + arrays may be slow (and in particular the pool may not be aware that it contains + enough free memory for the allocation request, and unnecessarily allocate + more memory). +
+
+ The pool interface is a simple
+ Object Usage interface with Null Return.
+
+ 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 +
+
+ There are two UserAllocator
+ classes provided. Both of them are in pool.hpp.
+
+ The default value for the template parameter UserAllocator
+ is always default_user_allocator_new_delete.
+
+
+struct default_user_allocator_new_delete +{ + typedef std::size_t size_type; + typedef std::ptrdiff_t difference_type; + + static char * malloc(const size_type bytes) + { return new (std::nothrow) char[bytes]; } + static void free(char * const block) + { delete [] block; } +}; + +struct default_user_allocator_malloc_free +{ + typedef std::size_t size_type; + typedef std::ptrdiff_t difference_type; + + static char * malloc(const size_type bytes) + { return reinterpret_cast<char *>(std::malloc(bytes)); } + static void free(char * const block) + { std::free(block); } +}; + +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); +}; ++
+
++ Example: +
+void func() +{ + boost::pool<> p(sizeof(int)); + for (int i = 0; i < 10000; ++i) + { + int * const t = p.malloc(); + ... // Do something with t; don't take the time to free() it. + } +} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed. ++
+
+
+ The template class object_pool
+ interface is an Object Usage interface with Null Return, but is aware
+ of the type of the object for which it is allocating chunks. On destruction,
+ any chunks that have been allocated from that object_pool
+ will have their destructors called.
+
+ object_pool.hpp
+ provides a template type that can be used for fast and efficient memory
+ allocation. It also provides automatic destruction of non-deallocated
+ objects.
+
+ For information on other pool-based interfaces, see the other Pool + Interfaces. +
++ Synopsis +
++
+template <typename ElementType, typename UserAllocator = default_user_allocator_new_delete> +class object_pool +{ + private: + object_pool(const object_pool &); + void operator=(const object_pool &); + + public: + typedef ElementType element_type; + typedef UserAllocator user_allocator; + typedef typename pool<UserAllocator>::size_type size_type; + typedef typename pool<UserAllocator>::difference_type difference_type; + + object_pool(); + ~object_pool(); + + element_type * malloc(); + void free(element_type * p); + bool is_from(element_type * p) const; + + element_type * construct(); + // other construct() functions + void destroy(element_type * p); +}; ++
+ Template Parameters +
++ ElementType +
++ The template parameter is the type of object to allocate/deallocate. + It must have a non-throwing destructor. +
++ UserAllocator +
++ Defines the method that the underlying Pool will use to allocate memory + from the system. Default is default_user_allocator_new_delete. See __UserAllocator + for details. +
++ Example: struct X { ... }; // has destructor + with side-effects. +
+void func() +{ + boost::object_pool<X> p; + for (int i = 0; i < 10000; ++i) + { + X * const t = p.malloc(); + ... // Do something with t; don't take the time to free() it. + } +} // on function exit, p is destroyed, and all destructors for the X objects are called. ++
+ The singleton_pool interface
+ at singleton_pool.hpp
+ is a Singleton Usage interface with Null Return. It's just the same as
+ the pool interface but with Singleton Usage instead.
+
+ Synopsis +
++
+template <typename Tag, unsigned RequestedSize, + typename UserAllocator = default_user_allocator_new_delete> +struct singleton_pool +{ + public: + typedef Tag tag; + typedef UserAllocator user_allocator; + typedef typename pool<UserAllocator>::size_type size_type; + typedef typename pool<UserAllocator>::difference_type difference_type; + + static const unsigned requested_size = RequestedSize; + + private: + static pool<size_type> p; // exposition only! + + singleton_pool(); + + public: + static bool is_from(void * ptr); + + static void * malloc(); + static void * ordered_malloc(); + static void * ordered_malloc(size_type n); + + static void free(void * ptr); + static void ordered_free(void * ptr); + static void free(void * ptr, std::size_t n); + static void ordered_free(void * ptr, size_type n); + + static bool release_memory(); + static bool purge_memory(); +}; ++
+ Notes +
+
+ The underlying pool p
+ referenced by the static functions in singleton_pool
+ is actually declared in a way so that it is:
+
main()
+ begins and after main() ends. All of the static functions
+ of singleton_pool synchronize their access to p.
+
+ Note that a different underlying pool
+ p exists for each different
+ set of template parameters, including implementation-specific ones.
+
+ Template Parameters +
++ Tag +
++ The Tag template parameter allows different unbounded + sets of singleton pools to exist. For example, the pool allocators use + two tag classes to ensure that the two different allocator types never + share the same underlying singleton pool. +
+
+ Tag is never actually used by singleton_pool.
+
+ RequestedSize The requested size of memory chunks + to allocate. This is passed as a constructor parameter to the underlying + pool. Must be greater than 0. +
++ UserAllocator +
++ Defines the method that the underlying pool will use to allocate memory + from the system. See User Allocators for details. +
++ Example: struct MyPoolTag { }; +
+typedef boost::singleton_pool<MyPoolTag, sizeof(int)> my_pool; +void func() +{ + for (int i = 0; i < 10000; ++i) + { + int * const t = my_pool::malloc(); + ... // Do something with t; don't take the time to free() it. + } + // Explicitly free all malloc()'ed ints. + my_pool::purge_memory(); +} ++
+ The pool_allocator interface
+ is a Singleton Usage interface with Exceptions. It is built on the singleton_pool
+ interface, and provides a Standard Allocator-compliant class (for use
+ in containers, etc.).
+
+ Introduction +
+
+ pool_alloc.hpp
+
+ Provides two template types that can be used for fast and efficient memory + allocation. 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 Standard or user-supplied containers. +
++ For information on other pool-based interfaces, see the other Pool + Interfaces. +
++ Synopsis +
++
+struct pool_allocator_tag { }; + +template <typename T, + typename UserAllocator = default_user_allocator_new_delete> +class pool_allocator +{ + public: + typedef UserAllocator user_allocator; + typedef T value_type; + typedef value_type * pointer; + typedef const value_type * const_pointer; + typedef value_type & reference; + typedef const value_type & const_reference; + typedef typename pool<UserAllocator>::size_type size_type; + typedef typename pool<UserAllcoator>::difference_type difference_type; + + template <typename U> + struct rebind + { typedef pool_allocator<U, UserAllocator> other; }; + + public: + pool_allocator(); + pool_allocator(const pool_allocator &); + // The following is not explicit, mimicking std::allocator [20.4.1] + template <typename U> + pool_allocator(const pool_allocator<U, UserAllocator> &); + pool_allocator & operator=(const pool_allocator &); + ~pool_allocator(); + + static pointer address(reference r); + static const_pointer address(const_reference s); + static size_type max_size(); + static void construct(pointer ptr, const value_type & t); + static void destroy(pointer ptr); + + bool operator==(const pool_allocator &) const; + bool operator!=(const pool_allocator &) const; + + static pointer allocate(size_type n); + static pointer allocate(size_type n, pointer); + static void deallocate(pointer ptr, size_type n); +}; + +struct fast_pool_allocator_tag { }; + +template <typename T + typename UserAllocator = default_user_allocator_new_delete> +class fast_pool_allocator +{ + public: + typedef UserAllocator user_allocator; + typedef T value_type; + typedef value_type * pointer; + typedef const value_type * const_pointer; + typedef value_type & reference; + typedef const value_type & const_reference; + typedef typename pool<UserAllocator>::size_type size_type; + typedef typename pool<UserAllocator>::difference_type difference_type; + + template <typename U> + struct rebind + { typedef fast_pool_allocator<U, UserAllocator> other; }; + + public: + fast_pool_allocator(); + fast_pool_allocator(const fast_pool_allocator &); + // The following is not explicit, mimicking std::allocator [20.4.1] + template <typename U> + fast_pool_allocator(const fast_pool_allocator<U, UserAllocator> &); + fast_pool_allocator & operator=(const fast_pool_allocator &); + ~fast_pool_allocator(); + + static pointer address(reference r); + static const_pointer address(const_reference s); + static size_type max_size(); + static void construct(pointer ptr, const value_type & t); + static void destroy(pointer ptr); + + bool operator==(const fast_pool_allocator &) const; + bool operator!=(const fast_pool_allocator &) const; + + static pointer allocate(size_type n); + static pointer allocate(size_type n, pointer); + static void deallocate(pointer ptr, size_type n); + + static pointer allocate(); + static void deallocate(pointer ptr); +}; ++
+ Template Parameters +
++ T The first template parameter is the type of object + to allocate/deallocate. +
++ UserAllocator Defines the method that the underlying + Pool will use to allocate memory from the system. See User Allocators + for details. +
++ Example: +
+void func() +{ + std::vector<int, boost::pool_allocator<int> > v; + for (int i = 0; i < 10000; ++i) + v.push_back(13); +} // Exiting the function does NOT free the system memory allocated by the pool allocator. + // You must call + // boost::singleton_pool<boost::pool_allocator_tag, sizeof(int)>::release_memory(); + // in order to force freeing the system memory. ++
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Pool allocation is a memory allocation scheme that is very fast, but limited + in its usage. For more information on pool allocation (also called simple + segregated storage, see concepts + concepts and Simple Segregated + Storage). +
++ Using Pools gives you more control over how memory is used in your program. + For example, you could have a situation where you want to allocate a bunch + of small objects at one point, and then reach a point in your program where + none of them are needed any more. Using pool interfaces, you can choose to + run their destructors or just drop them off into oblivion; the pool interface + will guarantee that there are no system memory leaks. +
++ Pools are generally used when there is a lot of allocation and deallocation + of small objects. Another common usage is the situation above, where many + objects may be dropped out of memory. +
++ In general, use Pools when you need a more efficient way to do unusual memory + control. +
+
+ pool_allocator is a more
+ general-purpose solution, geared towards efficiently servicing requests for
+ any number of contiguous chunks.
+
+ fast_pool_allocator is also
+ a general-purpose solution but is geared towards efficiently servicing requests
+ for one chunk at a time; it will work for contiguous chunks, but not as well
+ as pool_allocator.
+
+ If you are seriously concerned about performance, use fast_pool_allocator
+ when dealing with containers such as std::list,
+ and use pool_allocator when
+ dealing with containers such as std::vector.
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ Dynamic memory allocation has been a fundamental part of most + computer systems since roughly 1960... 1 +
++ Everyone uses dynamic memory allocation. If you have ever called malloc + or new, then you have used dynamic memory allocation. Most programmers + have a tendency to treat the heap as a “magic bag"”: + we ask it for memory, and it magically creates some for us. Sometimes we + run into problems because the heap is not magic. +
++ The heap is limited. Even on large systems (i.e., not embedded) with huge + amounts of virtual memory available, there is a limit. Everyone is aware + of the physical limit, but there is a more subtle, 'virtual' limit, that + limit at which your program (or the entire system) slows down due to the + use of virtual memory. This virtual limit is much closer to your program + than the physical limit, especially if you are running on a multitasking + system. Therefore, when running on a large system, it is considered nice + to make your program use as few resources as necessary, and release them + as soon as possible. When using an embedded system, programmers usually + have no memory to waste. +
++ The heap is complicated. It has to satisfy any type of memory request, + for any size, and do it fast. The common approaches to memory management + have to do with splitting the memory up into portions, and keeping them + ordered by size in some sort of a tree or list structure. Add in other + factors, such as locality and estimating lifetime, and heaps quickly become + very complicated. So complicated, in fact, that there is no known perfect + answer to the problem of how to do dynamic memory allocation. The diagrams + below illustrate how most common memory managers work: for each chunk of + memory, it uses part of that memory to maintain its internal tree or list + structure. Even when a chunk is malloc'ed out to a program, the memory + manager must save some information in it - usually + just its size. Then, when the block is free'd, the memory manager can easily + tell how large it is. +
+
+ 
+
+ 
+
+ Because of the complication of dynamic memory allocation, it is often inefficient + in terms of time and/or space. Most memory allocation algorithms store + some form of information with each memory block, either the block size + or some relational information, such as its position in the internal tree + or list structure. It is common for such header fields + to take up one machine word in a block that is being used by the program. + The obvious disadvantage, then, is when small objects are dynamically allocated. + For example, if ints were dynamically allocated, then automatically the + algorithm will reserve space for the header fields as well, and we end + up with a 50% waste of memory. Of course, this is a worst-case scenario. + However, more modern programs are making use of small objects on the heap; + and that is making this problem more and more apparent. Wilson et. al. + state that an average-case memory overhead is about ten to twenty percent2. This memory overhead will grow higher as more programs + use more smaller objects. It is this memory overhead that brings programs + closer to the virtual limit. +
++ In larger systems, the memory overhead is not as big of a problem (compared + to the amount of time it would take to work around it), and thus is often + ignored. However, there are situations where many allocations and/or deallocations + of smaller objects are taking place as part of a time-critical algorithm, + and in these situations, the system-supplied memory allocator is often + too slow. +
++ Simple segregated storage addresses both of these issues. Almost all memory + overhead is done away with, and all allocations can take place in a small + amount of (amortized) constant time. However, this is done at the loss + of generality; simple segregated storage only can allocate memory chunks + of a single size. +
++ Simple Segregated Storage is the basic idea behind the Boost Pool library. + Simple Segregated Storage is the simplest, and probably the fastest, memory + allocation/deallocation algorithm. It begins by partitioning a memory block + into fixed-size chunks. Where the block comes from is not important until + implementation time. A Pool is some object that uses Simple Segregated + Storage in this fashion. To illustrate: +
+
+ 
+
+ Each of the chunks in any given block are always the same size. This is + the fundamental restriction of Simple Segregated Storage: you cannot ask + for chunks of different sizes. For example, you cannot ask a Pool of integers + for a character, or a Pool of characters for an integer (assuming that + characters and integers are different sizes). +
++ Simple Segregated Storage works by interleaving a free list within the + unused chunks. For example: +
+
+ 
+
+ By interleaving the free list inside the chunks, each Simple Segregated + Storage only has the overhead of a single pointer (the pointer to the first + element in the list). It has no memory overhead for chunks that are in + use by the process. +
++ Simple Segregated Storage is also extremely fast. In the simplest case, + memory allocation is merely removing the first chunk from the free list, + a O(1) operation. In the case where the free list is empty, another block + may have to be acquired and partitioned, which would result in an amortized + O(1) time. Memory deallocation may be as simple as adding that chunk to + the front of the free list, a O(1) operation. However, more complicated + uses of Simple Segregated Storage may require a sorted free list, which + makes deallocation O(N). +
+
+ 
+
+ Simple Segregated Storage gives faster execution and less memory overhead + than a system-supplied allocator, but at the loss of generality. A good + place to use a Pool is in situations where many (noncontiguous) small objects + may be allocated on the heap, or if allocation and deallocation of the + same-sized objects happens repeatedly. +
++ Review the concepts + section if you are not already familiar with it. Remember that block is + a contiguous section of memory, which is partitioned or segregated into + fixed-size chunks. These chunks are what are allocated and deallocated + by the user. +
+
+ Each Pool has a single free list that can extend over a number of memory
+ blocks. Thus, Pool also has a linked list of allocated memory blocks. Each
+ memory block, by default, is allocated using new[], and all memory blocks are freed on destruction.
+ It is the use of new[]
+ that allows us to guarantee alignment.
+
+ Each block of memory is allocated as a POD type (specifically, an array
+ of characters) through operator
+ new[].
+ Let POD_size be the number
+ of characters allocated.
+
+ This follows from the following quote: +
++ [5.3.3/2] (Expressions::Unary expressions::Sizeof) ... When applied + to an array, the result is the total number of bytes in the array. This + implies that the size of an array of n elements is n times the size of + an element. +
++ Therefore, arrays cannot contain padding, though the elements within the + arrays may contain padding. +
+operator new[] (hereafter referred to as the block)
+ is properly aligned for any object of that size or smaller
+ + This follows from: +
+sizeof(Element) > POD_size
+ + Note that an object of that size can exist. One object of that size is + an array of the "actual" objects. +
++ Note that the block is properly aligned for an Element. This directly follows + from Predicate 2. +
++ This follows from Predicates 1 and 2, and the following quote: +
++ [3.9/9] (Basic concepts::Types) "An object type is a (possibly + cv-qualified) type that is not a function type, not a reference type, and + not a void type." +
++ (Specifically, array types are object types.) +
+p and
+ integer i, if p is properly aligned for the type it
+ points to, then p +
+ i (when well-defined) is properly
+ aligned for that type; in other words, if an array is properly aligned,
+ then each element in that array is properly aligned
+ + There are no quotes from the Standard to directly support this argument, + but it fits the common conception of the meaning of "alignment". +
+
+ Note that the conditions for p
+ + i
+ being well-defined are outlined in [5.7/5]. We do not quote that here,
+ but only make note that it is well-defined if p
+ and p +
+ i both point into or one past
+ the same array.
+
sizeof(Element)
+ be the least common multiple of sizes of several actual objects (T1, T2,
+ T3, ...)
+ i,
+ such that pe +
+ i is well-defined, then for each
+ n, there exists some integer jn
+ such that pn +
+ jn is well-defined and refers
+ to the same memory address as pe
+ + i
+
+ This follows naturally, since the memory block is an array of Elements,
+ and for each n, sizeof(Element) % sizeof(Tn)
+ == 0; thus, the boundary of each element in
+ the array of Elements is also a boundary of each element in each array
+ of Tn.
+
i, such
+ that pe +
+ i is well-defined, that address
+ (pe + i) is properly aligned for each type Tn
+
+ Since pe +
+ i is well-defined, then by Corollary
+ 3, pn +
+ jn is well-defined. It is properly
+ aligned from Predicate 2 and Corollaries 1 and 2.
+
+ The proof above covers alignment requirements for cutting chunks out of + a block. The implementation uses actual object sizes of: +
+requested_size);
+ this is the size of chunks requested by the user
+ void*
+ (pointer to void); this is because we interleave our free list through
+ the chunks
+ size_type; this is
+ because we store the size of the next block within each memory block
+ + Each block also contains a pointer to the next block; but that is stored + as a pointer to void and cast when necessary, to simplify alignment requirements + to the three types above. +
+
+ Therefore, alloc_size is
+ defined to be the largest of the sizes above, rounded up to be a multiple
+ of all three sizes. This guarantees alignment provided all alignments are
+ powers of two: something that appears to be true on all known platforms.
+
+ Each memory block consists of three main sections. The first section is + the part that chunks are cut out of, and contains the interleaved free + list. The second section is the pointer to the next block, and the third + section is the size of the next block. +
+
+ Each of these sections may contain padding as necessary to guarantee alignment
+ for each of the next sections. The size of the first section is number_of_chunks *
+ lcm(requested_size,
+ sizeof(void *), sizeof(size_type));
+ the size of the second section is lcm(sizeof(void *),
+ sizeof(size_type);
+ and the size of the third section is sizeof(size_type).
+
+ Here's an example memory block, where requested_size
+ == sizeof(void *)
+ == sizeof(size_type) == 4:
+
+ 
+
+ To show a visual example of possible padding, here's an example memory
+ block where requested_size == 8 and
+ sizeof(void *) == sizeof(size_type) == 4
+
+ 
+
+ The theorem above guarantees all alignment requirements for allocating + chunks and also implementation details such as the interleaved free list. + However, it does so by adding padding when necessary; therefore, we have + to treat allocations of contiguous chunks in a different way. +
+
+ Using array arguments similar to the above, we can translate any request
+ for contiguous memory for n
+ objects of requested_size
+ into a request for m contiguous chunks. m
+ is simply ceil(n * requested_size /
+ alloc_size),
+ where alloc_size is the
+ actual size of the chunks.
+
+ To illustrate: +
+
+ Here's an example memory block, where requested_size
+ == 1
+ and sizeof(void *) == sizeof(size_type) == 4:
+
+ 
+
+ Then, when the user deallocates the contiguous memory, we can split it + up into chunks again. +
++ Note that the implementation provided for allocating contiguous chunks + uses a linear instead of quadratic algorithm. This means that it may + not find contiguous free chunks if the free list is not ordered. Thus, + it is recommended to always use an ordered free list when dealing with + contiguous allocation of chunks. (In the example above, if Chunk 1 pointed + to Chunk 3 pointed to Chunk 2 pointed to Chunk 4, instead of being in + order, the contiguous allocation algorithm would have failed to find + any of the contiguous chunks). +
+
+ simple_segregated_storage.hpp
+ provides a template class simple_segregated_storage that controls access
+ to a free list of memory chunks.
+
+ Note that this is a very simple class, with unchecked preconditions on + almost all its functions. It is intended to be the fastest and smallest + possible quick memory allocator for example, something to use in embedded + systems. This class delegates many difficult preconditions to the user + (especially alignment issues). For more general usage, see the other Pool Interfaces. +
+template <typename SizeType = std::size_t>
+class simple_segregated_storage
+{
+ private:
+ simple_segregated_storage(const simple_segregated_storage &);
+ void operator=(const simple_segregated_storage &);
+
+ public:
+ typedef SizeType size_type;
+
+ simple_segregated_storage();
+ ~simple_segregated_storage();
+
+ static void * segregate(void * block,
+ size_type nsz, size_type npartition_sz,
+ void * end = 0);
+ void add_block(void * block,
+ size_type nsz, size_type npartition_sz);
+ void add_ordered_block(void * block,
+ size_type nsz, size_type npartition_sz);
+
+ bool empty() const;
+
+ void * malloc();
+ void free(void * chunk);
+ void ordered_free(void * chunk);
+ void * malloc_n(size_type n, size_type partition_sz);
+ void free_n(void * chunks, size_type n,
+ size_type partition_sz);
+ void ordered_free_n(void * chunks, size_type n,
+ size_type partition_sz);
+};
+
+
+ An object of type simple_segregated_storage<SizeType> is empty if its free list is empty.
+ If it is not empty, then it is ordered if its free list is ordered. A free
+ list is ordered if repeated calls to malloc() will result in a constantly-increasing
+ sequence of values, as determined by std::less<void *>. A member function is order-preserving
+ if the free-list maintains its order orientation (that is, an ordered free
+ list is still ordered after the member function call).
+
Table 1. Symbol Table
+|
+ + Symbol + + |
+
+ + Meaning + + |
+
|---|---|
|
+ + Store + + |
+
+ + simple_segregated_storage<SizeType> + + |
+
|
+ + t + + |
+
+ + value of type Store + + |
+
|
+ + u + + |
+
+ + value of type const Store + + |
+
|
+ + block, chunk, end + + |
+
+ + values of type void * + + |
+
|
+ + partition_sz, sz, n + + |
+
+ + values of type Store::size_type + + |
+
Table 2. Template Parameters
+|
+ + Parameter + + |
+
+ + Default + + |
+
+ + Requirements + + |
+
|---|---|---|
|
+ + SizeType + + |
+
+ + std::size_t + + |
+
+ + An unsigned integral type + + |
+
Table 3. Typedefs
+|
+ + Symbol + + |
+
+ + Type + + |
+
|---|---|
|
+ + size_type + + |
+
+ + SizeType + + |
+
Table 4. Constructors, Destructors, and State
+|
+ + Expression + + |
+
+ + Return Type + + |
+
+ + Post-Condition + + |
+
+ + Notes + + |
+
|---|---|---|---|
|
+ + Store() + + |
+
+ + not used + + |
+
+ + empty() + + |
+
+ + Constructs a new Store + + |
+
|
+ + (&t)->~Store() + + |
+
+ + not used + + |
++ | +
+ + Destructs the Store + + |
+
|
+ + u.empty() + + |
+
+ + bool + + |
++ | +
+ + Returns true if u is empty. Order-preserving. + + |
+
Table 5. Segregation
+|
+ + Expression + + |
+
+ + Return Type + + |
+
+ + Pre-Condition + + |
+
+ + Post-Condition + + |
+
+ + Semantic Equivalence + + |
+
+ + Notes + + |
+
|---|---|---|---|---|---|
|
+ + Store::segregate(block, sz, partition_sz, end) + + |
+
+ + void * + + |
+
+ + partition_sz >= sizeof(void *) partition_sz = sizeof(void + *) * i, for some integer i sz >= partition_sz block is properly + aligned for an array of objects of size partition_sz block is + properly aligned for an array of void * + + |
++ | ++ | +
+ + Interleaves a free list through the memory block specified by + block of size sz bytes, partitioning it into as many partition_sz-sized + chunks as possible. The last chunk is set to point to end, and + a pointer to the first chunck is returned (this is always equal + to block). This interleaved free list is ordered. O(sz). + + |
+
|
+ + Store::segregate(block, sz, partition_sz) + + |
+
+ + void * + + |
+
+ + Same as above + + |
++ | +
+ + Store::segregate(block, sz, partition_sz, 0) + + |
++ | +
|
+ + t.add_block(block, sz, partition_sz) + + |
+
+ + void + + |
+
+ + Same as above + + |
+
+ + !t.empty() + + |
++ | +
+ + Segregates the memory block specified by block of size sz bytes + into partition_sz-sized chunks, and adds that free list to its + own. If t was empty before this call, then it is ordered after + this call. O(sz). + + |
+
|
+ + t.add_ordered_block(block, sz, partition_sz) + + |
+
+ + void + + |
+
+ + Same as above + + |
+
+ + !t.empty() + + |
++ | +
+ + Segregates the memory block specified by block of size sz bytes + into partition_sz-sized chunks, and merges that free list into + its own. Order-preserving. O(sz). + + |
+
Table 6. Allocation and Deallocation
+|
+ + Expression + + |
+
+ + Return Type + + |
+
+ + Pre-Condition + + |
+
+ + Post-Condition + + |
+
+ + Semantic Equivalence + + |
+
+ + Notes + + |
+
|---|---|---|---|---|---|
|
+ + t.malloc() + + |
+
+ + void * + + |
+
+ + !t.empty() + + |
++ | ++ | +
+ + Takes the first available chunk from the free list and returns + it. Order-preserving. O(1). + + |
+
|
+ + t.free(chunk) + + |
+
+ + void + + |
+
+ + chunk was previously returned from a call to t.malloc() + + |
+
+ + !t.empty() + + |
++ | +
+ + Places chunk back on the free list. Note that chunk may not be + 0. O(1). + + |
+
|
+ + t.ordered_free(chunk) + + |
+
+ + void + + |
+
+ + Same as above + + |
+
+ + !t.empty() + + |
++ | +
+ + Places chunk back on the free list. Note that chunk may not be + 0. Order-preserving. O(N) with respect to the size of the free + list. + + |
+
|
+ + t.malloc_n(n, partition_sz) + + |
+
+ + void * + + |
++ | ++ | ++ | +
+ + Attempts to find a contiguous sequence of n partition_sz-sized + chunks. If found, removes them all from the free list and returns + a pointer to the first. If not found, returns 0. It is strongly + recommended (but not required) that the free list be ordered, + as this algorithm will fail to find a contiguous sequence unless + it is contiguous in the free list as well. Order-preserving. + O(N) with respect to the size of the free list. + + |
+
|
+ + t.free_n(chunk, n, partition_sz) + + |
+
+ + void + + |
+
+ + chunk was previously returned from a call to t.malloc_n(n, partition_sz) + + |
+
+ + !t.empty() + + |
+
+ + t.add_block(chunk, n * partition_sz, partition_sz) + + |
+
+ + Assumes that chunk actually refers to a block of chunks spanning + n * partition_sz bytes; segregates and adds in that block. Note + that chunk may not be 0. O(n). + + |
+
|
+ + t.ordered_free_n(chunk, n, partition_sz) + + |
+
+ + void + + |
+
+ + same as above + + |
+
+ + same as above + + |
+
+ + t.add_ordered_block(chunk, n * partition_sz, partition_sz) + + |
+
+ + Same as above, except it merges in the free list. Order-preserving. + O(N + n) where N is the size of the free list. + + |
+
+ Pool objects need to request memory blocks from the system, which the Pool + then splits into chunks to allocate to the user. By specifying a UserAllocator + template parameter to various Pool interfaces, users can control how those + system memory blocks are allocated. +
++ In the following table, UserAllocator is a User Allocator + type, block is a value of type char *, and n + is a value of type UserAllocator::size_type +
+Table 7. UserAllocator Requirements
+|
+ + Expression + + |
+
+ + Result + + |
+
+ + Description + + |
+
|---|---|---|
|
+ + UserAllocator::size_type + + |
++ | +
+ + An unsigned integral type that can represent the size of the + largest object to be allocated. + + |
+
|
+ + UserAllocator::difference_type + + |
++ | +
+ + A signed integral type that can represent the difference of any + two pointers. + + |
+
|
+ + UserAllocator::malloc(n) + + |
+
+ + char * + + |
+
+ + Attempts to allocate n bytes from the system. Returns 0 if out-of-memory. + + |
+
|
+ + UserAllocator::free(block) + + |
+
+ + void + + |
+
+ + block must have been previously returned from a call to UserAllocator::malloc. + + |
+
+ There are two UserAllocator classes provided in this library: default_user_allocator_new_delete
+ and default_user_allocator_malloc_free,
+ both in pool.hpp. The default value for the template parameter UserAllocator
+ is always default_user_allocator_new_delete.
+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ A jamfile.v2 is provided which can be run is the usual way, for example: +
++
+boost\libs\pool\test> bjam -a >pool_test.log+
+
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
++ See the Pool Interfaces + section that covers the different Pool interfaces supplied by this library. +
+
+ Forward declarations of all the exposed symbols for this library are in the
+ header made inscope by #include
+ <boost/pool/poolfwd.hpp>.
+
+ The library may use macros, which will be prefixed with BOOST_POOL_.
+ The exception to this rule are the include file guards, which (for file
+ xxx.hpp) is BOOST_xxx_HPP.
+
+ All exposed symbols defined by the library will be in namespace boost::. + All symbols used only by the implementation will be in namespace boost::details::pool. +
+
+ Every header used only by the implementation is in the subdirectory /detail/.
+
+ Any header in the library may include any other header in the library or + any system-supplied header at its discretion. +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+Provides a template type boost::object_pool<T, UserAllocator> that can be used for fast and efficient memory allocation of objects of type T. It also provides automatic destruction of non-deallocated objects.
+namespace boost { + template<typename T, typename UserAllocator> class object_pool; +}+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+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.
+namespace boost { + struct pool_allocator_tag; + + template<typename T, typename UserAllocator, typename Mutex, + unsigned NextSize, unsigned MaxSize> + class pool_allocator; + + template<typename UserAllocator, typename Mutex, unsigned NextSize, + unsigned MaxSize> + class pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>; + + struct fast_pool_allocator_tag; + + template<typename T, typename UserAllocator, typename Mutex, + unsigned NextSize, unsigned MaxSize> + class fast_pool_allocator; + + template<typename UserAllocator, typename Mutex, unsigned NextSize, + unsigned MaxSize> + class fast_pool_allocator<void, UserAllocator, Mutex, NextSize, MaxSize>; +}+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+Provides class pool: a fast memory allocator that guarantees proper alignment of all allocated chunks, and which extends and generalizes the framework provided by the simple segregated storage solution. Also provides two UserAllocator classes which can be used in conjuction with pool.
+namespace boost { + struct default_user_allocator_new_delete; + struct default_user_allocator_malloc_free; + + template<typename UserAllocator> class pool; +}+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+Forward declarations of all public (non-implemention) classes.
+| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+Simple Segregated Storage.
+A simple segregated storage implementation: simple segregated storage is the basic idea behind the Boost Pool library. Simple segregated storage is the simplest, and probably the fastest, memory allocation/deallocation algorithm. It begins by partitioning a memory block into fixed-size chunks. Where the block comes from is not important until implementation time. A Pool is some object that uses Simple Segregated Storage in this fashion.
++ +BOOST_POOL_VALIDATE_INTERNALS+
namespace boost { + template<typename SizeType> class simple_segregated_storage; +}+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
+The singleton_pool class allows other pool interfaces for types of the same size to share the same underlying pool.
Header singleton_pool.hpp provides a template class singleton_pool, which provides access to a pool as a singleton object.
namespace boost { + template<typename Tag, unsigned RequestedSize, typename UserAllocator, + typename Mutex, unsigned NextSize, unsigned MaxSize> + class singleton_pool; +}+
| + | + |
+ |
+Home | +Libraries | +People | +FAQ | +More | +
Copyright © 2000-2006 Stephen Cleary
Copyright © 2011 Paul A. Bristow
+ 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) +
+Table of Contents
+Last revised: December 15, 2011 at 11:24:47 GMT |
++ |