Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
C++ Boost

Boost Pool Interfaces

Introduction

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 Pools work.

Terminology and Tradeoffs

Object Usage vs. Singleton Usage

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.

Out-of-Memory Conditions: Exceptions vs. Null Return

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 throw an exception.

The Interfaces

pool

The pool interface is a simple Object Usage interface with Null Return.

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

object_pool

The 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.

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

singleton_pool

The singleton_pool interface is a Singleton Usage interface with Null Return. It's just the same as the pool interface but with Singleton Usage instead.

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 int's
  my_pool::purge_memory();
}

pool_alloc

The pool_alloc 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.).

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 that

Future Directions

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.


Valid HTML 4.01 Transitional

Revised 05 December, 2006

Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

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)