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.

Singleton Pool

Introduction

singleton_pool.hpp provides a template class singleton_pool, which provides access to a pool as a singleton object. For information on other pool-based interfaces, see the other pool interfaces.

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 that it is:

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

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.

Semantics

*Symbol Table*
Symbol	Meaning
SingletonPool	singleton_pool<Tag, RequestedSize, UserAllocator>
chunk	value of type void *
n	value of type size_type

*Typedefs/Static Const Values*
Expression	Type/Value
SingletonPool::tag	Tag
SingletonPool::user_allocator	UserAllocator
SingletonPool::size_type	pool<UserAllocator>::size_type
SingletonPool::difference_type	pool<UserAllocator>::difference_type
SingletonPool::requested_size	RequestedSize

*Functions*
Expression	Return Type	Semantic Equivalent
SingletonPool::is_from(chunk)	bool	SingletonPool::p.is_from(chunk); synchronized
SingletonPool::malloc()	void *	SingletonPool::p.malloc(); synchronized
SingletonPool::ordered_malloc(n)	void *	SingletonPool::p.ordered_malloc(n); synchronized
SingletonPool::free(chunk)	void	SingletonPool::p.free(chunk); synchronized
SingletonPool::ordered_free(chunk)	void	SingletonPool::p.ordered_free(chunk); synchronized
SingletonPool::free(chunk, n)	void	SingletonPool::p.free(chunk, n); synchronized
SingletonPool::ordered_free(chunk, n)	void	SingletonPool::p.ordered_free(chunk, n); synchronized
SingletonPool::release_memory()	bool	SingletonPool::p.release_memory(); synchronized
SingletonPool::purge_memory()	bool	SingletonPool::p.purge_memory(); synchronized

For more information on the semantics of these functions, see the pool interface.

Symbols

boost::singleton_pool

Implementation Details

Revised 05 December, 2006

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)