# 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

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)