Class template object

Class template object_pool

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.

Synopsis

// 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);
};

Description

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 construct/copy/destruct

explicit object_pool(const size_type arg_next_size = 32, 
                     const size_type arg_max_size = 0);

Constructs a new (empty by default) ObjectPool.

Requires:

next_size != 0.

```
~object_pool();
```

`object_pool` protected member functions

```
pool< UserAllocator > & store();
```
Returns:

The underlying boost:: pool storage used by *this.
```
const pool< UserAllocator > & store() const;
```
Returns:

The underlying boost:: pool storage used by *this.

`object_pool` protected static functions

```
static void *& nextof(void *const ptr);
```
Returns:

The next memory block after ptr (for the sake of code readability :)

`object_pool` public member functions

```
element_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.

	Note
This function may NOT be used to reliably test random pointer values!

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. detail/pool_construct.m4, when run with m4, will create the file detail/pool_construct.ipp, which only defines the construct functions for the proper number of arguments. The number of arguments may be passed into the file as an m4 macro, NumberOfArguments; if not provided, it will default to 3. For each different number of arguments (1 to NumberOfArguments), a template function is generated. There are the same number of template parameters as there are arguments, and each argument's type is a reference to that (possibly cv-qualified) template argument. Each possible permutation of the cv-qualifications is also generated. Because each permutation is generated for each possible number of arguments, the included file size grows exponentially in terms of the number of constructor arguments, not linearly. For the sake of rational compile times, only use as many arguments as you need. detail/pool_construct.bat and detail/pool_construct.sh are also provided to call m4, defining NumberOfArguments to be their command-line parameter. See these files for more details.

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.

detail/pool_construct.m4, when run with m4, will create the file detail/pool_construct.ipp, which only defines the construct functions for the proper number of arguments. The number of arguments may be passed into the file as an m4 macro, NumberOfArguments; if not provided, it will default to 3.

For each different number of arguments (1 to NumberOfArguments), a template function is generated. There are the same number of template parameters as there are arguments, and each argument's type is a reference to that (possibly cv-qualified) template argument. Each possible permutation of the cv-qualifications is also generated.

Because each permutation is generated for each possible number of arguments, the included file size grows exponentially in terms of the number of constructor arguments, not linearly. For the sake of rational compile times, only use as many arguments as you need.

detail/pool_construct.bat and detail/pool_construct.sh are also provided to call m4, defining NumberOfArguments to be their command-line parameter. See these files for more details.

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:

x

wanted next_size (must not be zero).