Boost Pool Library

Introduction

What is Pool?

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 the concepts document.

Why should I use Pool?

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.

When should I use Pool?

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.

How do I use Pool?

See the pool interfaces document, which covers the different Pool interfaces supplied by this library.

Library Structure and Dependencies

Forward declarations of all the exposed symbols for this library are in the header <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.

Installation

The Boost Pool library is a header file 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!

Building the Test Programs

The subdirectory "build" contains subdirectories for several different platforms. These subdirectories contain all necessary work-around code for that platform, as well as makefiles or IDE project files as appropriate.

Read the "readme.txt" in the proper subdirectory, if it exists.

The standard makefile targets are "all", "clean" (which deletes any intermediate files), and "veryclean" (which deletes any intermediate files and executables). All intermediate and executable files are built in the same directory as the makefile/project file. If there is a project file supplied instead of a makefile, "clean" and "veryclean" shell scripts/batch files will be provided.

Project files and makefiles for additional platforms may be sent to Stephen Cleary at scleary AT jerviswebb DOT com.

Documentation Map

• Overview of Pooling
  • concepts.html - The basic ideas behind pooling.
  • implementation/alignment.html - How we guarantee alignment portably.
  • interfaces.html - What interfaces are provided and when to use each one.
• Pool Exposed Interfaces
  • interfaces/simple_segregated_storage.html - Not for the faint of heart; embedded programmers only.
  • interfaces/pool.html - The basic pool interface.
  • interfaces/singleton_pool.html - The basic pool interface as a thread-safe singleton.
  • interfaces/object_pool.html - A type-oriented (instead of size-oriented) pool interface.
  • interfaces/pool_alloc.html - A Standard Allocator pool interface based on singleton_pool.
  • interfaces/user_allocator.html - OK, not a pool interface, but it describes how the user can control how Pools allocate system memory.
• Pool Implementation Details and Extensions
  • Interface Implementations and Extensions
    • implementation/simple_segregated_storage.html
    • implementation/pool.html
    • implementation/singleton_pool.html
    • implementation/object_pool.html
    • implementation/pool_alloc.html
  • Components Used Only by the Implementation
    • implementation/ct_gcd_lcm.html - Compile-time GCD and LCM.
    • implementation/for.html - Description of an m4 component.
    • implementation/gcd_lcm.html - Run-time GCD and LCM.
    • implementation/guard.html - Auto lock/unlock for mutex.
    • implementation/mutex.html - Platform-dependent mutex type.
    • implementation/pool_construct.html - The system for supporting more constructor arguments in object_pool.
    • implementation/singleton.html - Singleton that avoids static initialization problem.

Future Directions

Another pool interface will be written: a base class for per-class pool allocation.

Acknowledgements

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!

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)