// bdlma_multipoolallocator.h -*-C++-*-
#ifndef INCLUDED_BDLMA_MULTIPOOLALLOCATOR
#define INCLUDED_BDLMA_MULTIPOOLALLOCATOR
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
//@PURPOSE: Provide a memory-pooling allocator of heterogeneous block sizes.
//
//@CLASSES:
// bdlma::MultipoolAllocator: allocator managing varying-size memory pools
//
//@SEE_ALSO: bdlma_pool, bdlma_multipool
//
//@DESCRIPTION: This component provides a general-purpose, managed allocator,
// 'bdlma::MultipoolAllocator', that implements the 'bdlma::ManagedAllocator'
// protocol and provides an allocator that maintains a configurable number of
// 'bdlma::Pool' objects, each dispensing maximally-aligned memory blocks of a
// unique size. The 'bdlma::Pool' objects are placed in an array, starting at
// index 0, with each successive pool managing memory blocks of a size twice
// that of the previous pool. Each multipool allocation (deallocation) request
// allocates memory from (returns memory to) the internal pool managing memory
// blocks of the smallest size not less than the requested size, or else from a
// separately managed list of memory blocks, if no internal pool managing
// memory blocks of sufficient size exists. Both the 'release' method and the
// destructor of a 'bdlma::MultipoolAllocator' release all memory currently
// allocated via the object.
//..
// ,-------------------------.
// ( bdlma::MultipoolAllocator )
// `-------------------------'
// | ctor/dtor
// | maxPooledBlockSize
// | numPools
// | reserveCapacity
// V
// ,-----------------------.
// ( bdlma::ManagedAllocator )
// `-----------------------'
// | release
// V
// ,----------------.
// ( bslma::Allocator )
// `----------------'
// allocate
// deallocate
//..
// The main difference between a 'bdlma::MultipoolAllocator' and a
// 'bdlma::Multipool' is that, very often, a 'bdlma::MultipoolAllocator' is
// managed through a 'bslma::Allocator' pointer. Hence, every call to the
// 'allocate' method invokes a virtual function call, which is slower than
// invoking the non-virtual 'allocate' method on a 'bdlma::Multipool'.
// However, since 'bslma::Allocator *' is widely used across BDE interfaces,
// 'bdlma::MultipoolAllocator' is more general purpose than 'bdlma::Multipool'.
//
///Configuration at Construction
///-----------------------------
// When creating a 'bdlma::MultipoolAllocator', clients can optionally
// configure:
//
//: 1 NUMBER OF POOLS -- the number of internal pools (the block size managed
//: by the first pool is eight bytes, with each successive pool managing
//: blocks of a size twice that of the previous pool).
//: 2 GROWTH STRATEGY -- geometrically growing chunk size starting from 1 (in
//: terms of the number of memory blocks per chunk), or fixed chunk size,
//: specified as either:
//: o the unique growth strategy for all pools, or
//: o (if the number of pools is specified) an array of growth strategies
//: corresponding to each individual pool.
//: If the growth strategy is not specified, geometric growth is used for all
//: pools.
//: 3 MAX BLOCKS PER CHUNK -- the maximum number of memory blocks within a
//: chunk, specified as either:
//: o the unique maximum-blocks-per-chunk value for all of the pools, or
//: o an array of maximum-blocks-per-chunk values corresponding to each
//: individual pool.
//: If the maximum blocks per chunk is not specified, an
//: implementation-defined default value is used. Note that the maximum
//: blocks per chunk can be configured only if the number of pools is also
//: configured.
//: 4 BASIC ALLOCATOR -- the allocator used to supply memory (to replenish an
//: internal pool, or directly if the maximum block size is exceeded). If
//: not specified, the currently installed default allocator is used (see
//: 'bslma_default').
//
// A default-constructed multipool allocator has a relatively small,
// implementation-defined number of pools, 'N', with respective block sizes
// ranging from '2^3 = 8' to '2^(N+2)'. By default, the initial chunk size,
// (i.e., the number of blocks of a given size allocated at once to replenish a
// pool's memory) is 1, and each pool's chunk size grows geometrically until it
// reaches an implementation-defined maximum, at which it is capped. Finally,
// unless otherwise specified, all memory comes from the allocator that was the
// currently installed default allocator at the time the
// 'bdlma::MultipoolAllocator' was created.
//
// Using the various pooling options described above, we can configure the
// number of pools maintained, whether replenishment should be adaptive (i.e.,
// geometric starting with 1) or fixed at a maximum chunk size, what that
// maximum chunk size should be (which need not be an integral power of 2), and
// the underlying allocator used to supply memory. Note that both GROWTH
// STRATEGY and MAX BLOCKS PER CHUNK can be specified separately either as a
// single value applying to all of the maintained pools, or as an array of
// values, with the elements applying to each individually maintained pool.
//
///Usage
///-----
// This section illustrates intended use of this component.
//
///Example 1: Using a 'bdlma::MultipoolAllocator'
/// - - - - - - - - - - - - - - - - - - - - - - -
// A 'bdlma::MultipoolAllocator' can be used to supply memory to node-based
// data structures such as 'bsl::set', 'bsl::list', and 'bsl::map'. Suppose we
// are implementing a container of named graphs, where a graph is defined by a
// set of edges and a set of nodes. The various fixed-sized nodes and edges
// can be efficiently allocated by a 'bdlma::MultipoolAllocator'.
//
// First, the edge class, 'my_Edge', is defined as follows:
//..
// class my_Node;
//
// class my_Edge {
// // This class represents an edge within a graph. Both ends of an edge
// // must be connected to nodes.
//
// // DATA
// my_Node *d_first; // first node
// my_Node *d_second; // second node
//
// // ...
//
// public:
// // CREATORS
// my_Edge(my_Node *first, my_Node *second);
// // Create an edge that connects to the specified 'first' and
// // 'second' nodes.
//
// // ...
// };
//
// // CREATORS
// my_Edge::my_Edge(my_Node *first, my_Node *second)
// : d_first(first)
// , d_second(second)
// {
// }
//..
// Then, the node class, 'my_Node', is defined as follows:
//..
// class my_Node {
// // This class represents a node within a graph. A node can be
// // connected to any number of edges.
//
// // DATA
// bsl::set<my_Edge *> d_edges; // set of edges this node connects to
//
// // ...
//
// private:
// // Not implemented:
// my_Node(const my_Node&);
//
// public:
// // TRAITS
// BSLMF_NESTED_TRAIT_DECLARATION(my_Node, bslma::UsesBslmaAllocator);
//
// // CREATORS
// explicit my_Node(bslma::Allocator *basicAllocator = 0);
// // Create a node not connected to any other nodes. Optionally
// // specify a 'basicAllocator' used to supply memory. If
// // 'basicAllocator' is 0, the currently installed default allocator
// // is used.
//
// // ...
// };
//
// // CREATORS
// my_Node::my_Node(bslma::Allocator *basicAllocator)
// : d_edges(basicAllocator)
// {
// }
//..
// Then, we define the graph class, 'my_Graph', as follows:
//..
// class my_Graph {
// // This class represents a graph having sets of nodes and edges.
//
// // DATA
// bsl::set<my_Edge> d_edges; // set of edges in this graph
// bsl::set<my_Node> d_nodes; // set of nodes in this graph
//
// // ...
//
// private:
// // Not implemented:
// my_Graph(const my_Graph&);
//
// public:
// // TRAITS
// BSLMF_NESTED_TRAIT_DECLARATION(my_Graph, bslma::UsesBslmaAllocator);
//
// // CREATORS
// explicit my_Graph(bslma::Allocator *basicAllocator = 0);
// // Create an empty graph. Optionally specify a 'basicAllocator'
// // used to supply memory. If 'basicAllocator' is 0, the currently
// // installed default allocator is used.
//
// // ...
// };
//
// my_Graph::my_Graph(bslma::Allocator *basicAllocator)
// : d_edges(basicAllocator)
// , d_nodes(basicAllocator)
// {
// }
//..
// Next, the container for the collection of named graphs,
// 'my_NamedGraphContainer', is defined as follows:
//..
// class my_NamedGraphContainer {
// // This class stores a map that indexes graph names to graph objects.
//
// // DATA
// bsl::map<bsl::string, my_Graph> d_graphMap; // map from graph name to
// // graph
//
// private:
// // Not implemented:
// my_NamedGraphContainer(const my_NamedGraphContainer&);
//
// public:
// // TRAITS
// BSLMF_NESTED_TRAIT_DECLARATION(my_NamedGraphContainer,
// bslma::UsesBslmaAllocator);
//
// // CREATORS
// explicit my_NamedGraphContainer(bslma::Allocator *basicAllocator = 0);
// // Create an empty named graph container. Optionally specify a
// // 'basicAllocator' used to supply memory. If 'basicAllocator' is
// // 0, the currently installed default allocator is used.
//
// // ...
// };
//
// // CREATORS
// my_NamedGraphContainer::my_NamedGraphContainer(
// bslma::Allocator *basicAllocator)
// : d_graphMap(basicAllocator)
// {
// }
//..
// Finally, in 'main', we can create a 'bdlma::MultipoolAllocator' and pass it
// to our 'my_NamedGraphContainer'. Since we know that the maximum block size
// needed is 32 ('sizeof(my_Graph)'), we can calculate the number of pools
// needed by using the formula given in the "Configuration at Construction"
// section:
//..
// largestPoolSize == 2 ^ (N + 2)
//..
// When solved for the above equation, the smallest 'N' that satisfies this
// relationship is 3:
//..
// int main()
// {
// enum { k_NUM_POOLS = 3 };
//
// bdlma::MultipoolAllocator multipoolAllocator(NUM_POOLS);
//
// my_NamedGraphContainer container(&multipoolAllocator);
// }
//..
//
///Example 2: Performance of a 'bdlma::MultipoolAllocator'
/// - - - - - - - - - - - - - - - - - - - - - - - - - - -
// A 'bdlma::MultipoolAllocator' can greatly improve efficiency when it is used
// to supply memory to node-based data structures that frequently both insert
// and remove nodes, while growing to significant size before being destroyed.
// The following experiment will illustrate the benefits of using a
// 'bdlma::MultipoolAllocator' under this scenario by comparing the following 3
// different allocator uses:
//
//: 1 Using the 'bslma::NewDeleteAllocator'.
//:
//: 2 Using a 'bdlma::MultipoolAllocator' as a substitute for the
//: 'bslma::NewDeleteAllocator'.
//:
//: 3 Exploiting the managed aspect of 'bdlma::MultipoolAllocator' by avoiding
//: invocation of the destructor of the data structure, since the
//: destruction of the allocator will automatically reclaim all memory.
//
// First, we create a test data structure that contains three 'bsl::list's.
// Each list holds a different type of object, where each type has a different
// size. For simplicity, we create these different object types as different
// instantiations of a template class, parameterized on the object size:
//..
// template <int OBJECT_SIZE>
// class my_TestObject {
//
// // DATA
// char d_data[OBJECT_SIZE];
// };
//..
// Again, for simplicity, the sizes of these objects are chosen to be 20, 40,
// and 80, instead of being parameterized as part of the test data structure:
//..
// class my_TestDataStructure {
//
// // PRIVATE TYPES
// typedef my_TestObject<20> Obj1;
// typedef my_TestObject<40> Obj2;
// typedef my_TestObject<80> Obj3;
//
// // DATA
// bsl::list<Obj1> d_list1;
// bsl::list<Obj2> d_list2;
// bsl::list<Obj3> d_list3;
//..
// The test will consist of the following steps:
//
//: 1 Push back into 'd_list1', then 'd_list2', then 'd_list3'.
//: 2 Repeat #1.
//: 3 Pop front from 'd_list1', then 'd_list2', then 'd_list3'.
//
// The above 3 steps will be repeated 'n' times, where 'n' is a parameter
// specified by the user. This process will both grow the list and incorporate
// a large number of node removals. Note that nodes are removed from the front
// of the list to simulate a particular real-world usage, where nodes removed
// are rarely those recently added (this also removes the possibility of noise
// from potential optimizations with relinquishing memory blocks that are most
// recently allocated).
//..
// public:
// // CREATORS
// my_TestDataStructure(bslma::Allocator *basicAllocator = 0);
//
// // MANIPULATORS
// void pop();
//
// void push();
// };
//
// // CREATORS
// my_TestDataStructure::my_TestDataStructure(
// bslma::Allocator *basicAllocator)
// : d_list1(basicAllocator)
// , d_list2(basicAllocator)
// , d_list3(basicAllocator)
// {
// }
//..
// The 'push' method will push into the 3 'bsl::list' objects managed by
// 'my_TestDataStructure' sequentially. Similarly, the 'pop' method will pop
// from the lists sequentially:
//..
// // MANIPULATORS
// void my_TestDataStructure::push()
// {
// // Push to the back of the 3 lists.
//
// d_list1.push_back(Obj1());
// d_list2.push_back(Obj2());
// d_list3.push_back(Obj3());
// }
//
// void my_TestDataStructure::pop()
// {
// // Pop from the front of the 3 lists.
//
// d_list1.pop_front();
// d_list2.pop_front();
// d_list3.pop_front();
// }
//..
// The above 'push' and 'pop' methods will allow us to evaluate the cost to add
// and remove nodes using different allocators. To evaluate the cost of
// destruction (and hence deallocation of all allocated memory in the list
// objects), we supply a 'static' 'test' method within a 'my_TestUtil' class to
// create the test mechanism, run the test, and destroy the test mechanism.
//
// The 'test' method accepts a 'testLengthFactor' argument specified by the
// user to control the length of the test. The effect of 'testLengthFactor' is
// shown below:
//..
// testLengthFactor test size n iterations
// ---------------- ---------------- -------- ----------
// 4 10^4 = 10000 1 10000
// 10 1000
// 100 100
// 1000 10
// 10000 1
//
// 5 10^5 = 100000 1 100000
// 10 10000
// 100 1000
// 1000 100
// 10000 10
// 100000 1
//
// 6 10^6 = 1000000 1 1000000
// 10 100000
// 100 10000
// 1000 1000
// 10000 100
// 100000 10
// 1000000 1
//
// // ...
//..
// For each row of the specified 'testLengthFactor', a 'my_TestDataStructure'
// will be created "iterations" times, and each time the lists within the data
// structure will grow by invoking 'push' twice and 'pop' once. Note that "n"
// measures the effect of insertion and removal of nodes, while "iterations"
// measures the effect of construction and destruction of entire lists of
// nodes.
//
// The 'test' method also accepts a 'bslma::Allocator *' to be used as the
// allocator used to construct the test mechanism and its internal lists:
//..
// class my_TestUtil {
//
// public:
// // CLASS METHODS
// static
// void test(int testLengthFactor, bslma::Allocator *basicAllocator)
// {
// int n = 1;
// int iterations = 1;
//
// for (int i = 0; i < testLengthFactor; ++i) {
// iterations *= 10;
// }
//
// for (int i = 0; i <= testLengthFactor; ++i) {
// bsls::Stopwatch timer;
// timer.start();
//
// for (int j = 0; j < iterations; ++j) {
// my_TestDataStructure tds(basicAllocator);
//
// // Testing cost of insertion and deletion.
//
// for (int k = 0; k < n; ++k) {
// tds.push();
// tds.push();
// tds.pop();
// }
//
// // Testing cost of destruction.
// }
//
// timer.stop();
//
// printf("%d\t%d\t%d\t%1.6f\n", testLengthFactor,
// n,
// iterations,
// timer.elapsedTime());
//
// n *= 10;
// iterations /= 10;
// }
// }
//..
// Next, to fully test the benefit of being able to relinquish all allocated
// memory at once, we use the 'testManaged' method, which accepts only managed
// allocators. Instead of creating the test mechanism on the stack, the test
// mechanism will be created on the heap. After running the test, the
// 'release' method of the allocator will reclaim all outstanding allocations
// at once, eliminating the need to run the destructor of the test mechanism:
//..
// static
// void testManaged(int testLengthFactor,
// bdlma::ManagedAllocator *managedAllocator)
// {
// int n = 1;
// int iterations = 1;
//
// for (int i = 0; i < testLengthFactor; ++i) {
// iterations *= 10;
// }
//
// for (int i = 0; i <= testLengthFactor; ++i) {
// bsls::Stopwatch timer;
// timer.start();
//
// for (int j = 0; j < iterations; ++j) {
// my_TestDataStructure *tmPtr = new(*managedAllocator)
// my_TestDataStructure(managedAllocator);
//
// // Testing cost of insertion and deletion.
//
// for (int k = 0; k < n; ++k) {
// tmPtr->push();
// tmPtr->push();
// tmPtr->pop();
// }
//
// // Testing cost of destruction.
//
// managedAllocator->release();
// }
//
// timer.stop();
//
// printf("%d\t%d\t%d\t%1.6f\n", testLengthFactor,
// n,
// iterations,
// timer.elapsedTime());
//
// n *= 10;
// iterations /= 10;
// }
// }
// };
//..
// Finally, in main, we run the test with the different allocators and
// different allocator configurations based on command line arguments:
//..
// {
// int testLengthFactor = 5;
// const int NUM_POOLS = 10;
//
// if (argc > 2) {
// testLengthFactor = bsl::atoi(argv[2]);
// }
//
// char growth = 'g';
// if (argc > 3) {
// growth = argv[3][0];
// if (growth != 'g' && growth != 'c') {
// printf("[g]eometric or [c]onstant growth must be used\n");
// return -1;
// }
// }
//
// int maxChunkSize = 32;
// if (argc > 4) {
// maxChunkSize = bsl::atoi(argv[4]);
// if (maxChunkSize <= 0) {
// printf("maxChunkSize must be >= 1");
// }
// }
//
// bsls::BlockGrowth::Strategy strategy = growth == 'g'
// ? bsls::BlockGrowth::BSLS_GEOMETRIC
// : bsls::BlockGrowth::BSLS_CONSTANT;
//
// printf("\nNew Delete Allocator:\n\n");
// {
// bslma::Allocator *nda = bslma::NewDeleteAllocator::allocator(0);
// my_TestUtil::test(testLengthFactor, nda);
// }
//
// printf("\nMultipool Allocator with [%c], [%d]:\n\n", growth,
// maxChunkSize);
// {
// bdlma::MultipoolAllocator ma(NUM_POOLS, strategy, maxChunkSize);
// my_TestUtil::test(testLengthFactor, &ma);
// }
//
// printf("\nMultipool Allocator Managed with [%c], [%d]:\n\n", growth,
// maxChunkSize);
// {
// bdlma::MultipoolAllocator ma(NUM_POOLS, strategy, maxChunkSize);
// my_TestUtil::testManaged(testLengthFactor, &ma);
// }
//
// return 0;
// }
//..
// An excerpt of the results of the test running on IBM under optimized mode,
// using default constructed 'bdlma::MultipoolAllocator' parameters, is shown
// below:
//..
// New Delete Allocator:
//
// 6 1 1000000 3.006253
// 6 10 100000 2.369734
// 6 100 10000 2.598567
// 6 1000 1000 2.604546
// 6 10000 100 2.760319
// 6 100000 10 3.085765
// 6 1000000 1 4.465030
//
// Multipool Allocator with [g], [32]:
//
// 6 1 1000000 0.766064
// 6 10 100000 0.408509
// 6 100 10000 0.357019
// 6 1000 1000 0.436448
// 6 10000 100 0.643206
// 6 100000 10 0.932662
// 6 1000000 1 0.938906
//
// Multipool Allocator Managed with [g], [32]:
//
// 6 1 1000000 1.958663
// 6 10 100000 0.463185
// 6 100 10000 0.371201
// 6 1000 1000 0.357816
// 6 10000 100 0.368082
// 6 100000 10 0.388422
// 6 1000000 1 0.529167
//..
// It is clear that using a 'bdlma::MultipoolAllocator' results in an
// improvement in memory allocation by a factor of about 4. Furthermore, if
// the managed aspect of the multipool allocator is exploited, the cost of
// destruction rapidly decreases in relative terms as the list grows larger
// (increasing 'n').
#include <bdlscm_version.h>
#include <bdlma_managedallocator.h>
#include <bdlma_multipool.h>
#include <bslma_allocator.h>
#include <bsls_performancehint.h>
#include <bsls_types.h>
namespace BloombergLP {
namespace bdlma {
// ========================
// class MultipoolAllocator
// ========================
class MultipoolAllocator : public ManagedAllocator {
// This class implements the 'bdlma::ManagedAllocator' protocol to provide
// an allocator that maintains a configurable number of 'bdlma::Pool'
// objects, each dispensing memory blocks of a unique size. The
// 'bdlma::Pool' objects are placed in an array, with each successive pool
// managing memory blocks of size twice that of the previous pool. Each
// multipool allocation (deallocation) request allocates memory from
// (returns memory to) the internal pool having the smallest block size not
// less than the requested size, or, if no pool manages memory blocks of
// sufficient sized, from a separately managed list of memory blocks. Both
// the 'release' method and the destructor of a 'bdlma::MultipoolAllocator'
// release all memory currently allocated via the object.
// DATA
Multipool d_multipool; // manager for allocated memory blocks
private:
// NOT IMPLEMENTED
MultipoolAllocator(const MultipoolAllocator&);
MultipoolAllocator& operator=(const MultipoolAllocator&);
public:
// CREATORS
explicit
MultipoolAllocator(bslma::Allocator *basicAllocator = 0);
explicit
MultipoolAllocator(int numPools, bslma::Allocator *basicAllocator = 0);
explicit
MultipoolAllocator(bsls::BlockGrowth::Strategy growthStrategy,
bslma::Allocator *basicAllocator = 0);
MultipoolAllocator(int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
bslma::Allocator *basicAllocator = 0);
MultipoolAllocator(int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
int maxBlocksPerChunk,
bslma::Allocator *basicAllocator = 0);
// Create a multipool allocator. Optionally specify 'numPools',
// indicating the number of internally created 'bdlma::Pool' objects;
// the block size of the first pool is 8 bytes, with the block size of
// each additional pool successively doubling. If 'numPools' is not
// specified, an implementation-defined number of pools 'N' -- covering
// memory blocks ranging in size from '2^3 = 8' to '2^(N+2)' -- are
// created. Optionally specify a 'growthStrategy' indicating whether
// the number of blocks allocated at once for every internally created
// 'bdlma::Pool' should be either fixed or grow geometrically, starting
// with 1. If 'growthStrategy' is not specified, the allocation
// strategy for each internally created 'bdlma::Pool' object is
// geometric, starting from 1. If 'numPools' and 'growthStrategy' are
// specified, optionally specify a 'maxBlocksPerChunk', indicating the
// maximum number of blocks to be allocated at once when a pool must be
// replenished. If 'maxBlocksPerChunk' is not specified, an
// implementation-defined value is used. Optionally specify a
// 'basicAllocator' used to supply memory. If 'basicAllocator' is 0,
// the currently installed default allocator is used. Memory
// allocation (and deallocation) requests will be satisfied using the
// internally maintained pool managing memory blocks of the smallest
// size not less than the requested size, or directly from the
// underlying allocator (supplied at construction), if no internal pool
// managing memory blocks of sufficient size exists. The behavior is
// undefined unless '1 <= numPools' and '1 <= maxBlocksPerChunk'. Note
// that, on platforms where
// '8 < bsls::AlignmentUtil::BSLS_MAX_ALIGNMENT', excess memory may be
// allocated for pools managing smaller blocks. Also note that
// 'maxBlocksPerChunk' need not be an integral power of 2; if geometric
// growth would exceed the maximum value, the chunk size is capped at
// that value.
MultipoolAllocator(int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
bslma::Allocator *basicAllocator = 0);
MultipoolAllocator(int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
int maxBlocksPerChunk,
bslma::Allocator *basicAllocator = 0);
MultipoolAllocator(int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
const int *maxBlocksPerChunkArray,
bslma::Allocator *basicAllocator = 0);
MultipoolAllocator(
int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
const int *maxBlocksPerChunkArray,
bslma::Allocator *basicAllocator = 0);
// Create a multipool allocator having the specified 'numPools',
// indicating the number of internally created 'bdlma::Pool' objects;
// the block size of the first pool is 8 bytes, with the block size of
// each additional pool successively doubling. Optionally specify a
// 'growthStrategy' indicating whether the number of blocks allocated
// at once for every internally created 'bdlma::Pool' should be either
// fixed or grow geometrically, starting with 1. If 'growthStrategy'
// is not specified, optionally specify a 'growthStrategyArray',
// indicating the strategies for each individual 'bdlma::Pool' created
// by this object. If neither 'growthStrategy' nor
// 'growthStrategyArray' is specified, the allocation strategy for each
// internally created 'bdlma::Pool' object will grow geometrically,
// starting from 1. Optionally specify a 'maxBlocksPerChunk',
// indicating the maximum number of blocks to be allocated at once when
// a pool must be replenished. If 'maxBlocksPerChunk' is not
// specified, optionally specify a 'maxBlocksPerChunkArray', indicating
// the maximum number of blocks to allocate at once for each
// individually created 'bdlma::Pool' object. If neither
// 'maxBlocksPerChunk' nor 'maxBlocksPerChunkArray' is specified, an
// implementation-defined value is used. Optionally specify a
// 'basicAllocator' used to supply memory. If 'basicAllocator' is 0,
// the currently installed default allocator is used. Memory
// allocation (and deallocation) requests will be satisfied using the
// internally maintained pool managing memory blocks of the smallest
// size not less than the requested size, or directly from the
// underlying allocator (supplied at construction), if no internal pool
// managing memory blocks of sufficient size exists. The behavior is
// undefined unless '1 <= numPools', 'growthStrategyArray' has at least
// 'numPools' strategies, '1 <= maxBlocksPerChunk', and
// 'maxBlocksPerChunkArray' has at least 'numPools' positive values.
// Note that, on platforms where
// '8 < bsls::AlignmentUtil::BSLS_MAX_ALIGNMENT', excess memory may be
// allocated for pools managing smaller blocks. Also note that the
// maximum need not be an integral power of 2; if geometric growth
// would exceed a maximum value, the chunk size is capped at that
// value.
virtual ~MultipoolAllocator();
// Destroy this multipool allocator. All memory allocated from this
// allocator is released.
// MANIPULATORS
void reserveCapacity(bsls::Types::size_type size, int numObjects);
// Reserve memory from this multipool allocator to satisfy memory
// requests for at least the specified 'numObjects' having the
// specified 'size' (in bytes) before the pool replenishes. If 'size'
// is 0, this method has no effect. The behavior is undefined unless
// 'size <= maxPooledBlockSize()' and '0 <= numObjects'.
// Virtual Functions
virtual void *allocate(bsls::Types::size_type size);
// Return the address of a contiguous block of maximally-aligned memory
// of (at least) the specified 'size' (in bytes). If 'size' is 0, no
// memory is allocated and 0 is returned. If
// 'size > maxPooledBlockSize()', the memory allocation is managed
// directly by the underlying allocator, but will not be pooled .
virtual void deallocate(void *address);
// Return the memory block at the specified 'address' back to this
// allocator for reuse. If 'address' is 0, this method has no effect.
// The behavior is undefined unless 'address' was allocated by this
// allocator, and has not already been deallocated.
virtual void release();
// Release all memory currently allocated through this multipool
// allocator.
// ACCESSORS
int numPools() const;
// Return the number of pools managed by this multipool allocator.
bsls::Types::size_type maxPooledBlockSize() const;
// Return the maximum size of memory blocks that are pooled by this
// multipool allocator. Note that the maximum value is defined as:
//..
// 2 ^ (numPools + 2)
//..
// where 'numPools' is either specified at construction, or an
// implementation-defined value.
};
// ============================================================================
// INLINE DEFINITIONS
// ============================================================================
// ------------------------
// class MultipoolAllocator
// ------------------------
// CREATORS
inline
MultipoolAllocator::MultipoolAllocator(
bslma::Allocator *basicAllocator)
: d_multipool(basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
bsls::BlockGrowth::Strategy growthStrategy,
bslma::Allocator *basicAllocator)
: d_multipool(growthStrategy, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, growthStrategy, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, growthStrategyArray, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
int maxBlocksPerChunk,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, growthStrategy, maxBlocksPerChunk, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
int maxBlocksPerChunk,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, growthStrategyArray, maxBlocksPerChunk, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
bsls::BlockGrowth::Strategy growthStrategy,
const int *maxBlocksPerChunkArray,
bslma::Allocator *basicAllocator)
: d_multipool(numPools, growthStrategy, maxBlocksPerChunkArray, basicAllocator)
{
}
inline
MultipoolAllocator::MultipoolAllocator(
int numPools,
const bsls::BlockGrowth::Strategy *growthStrategyArray,
const int *maxBlocksPerChunkArray,
bslma::Allocator *basicAllocator)
: d_multipool(numPools,
growthStrategyArray,
maxBlocksPerChunkArray,
basicAllocator)
{
}
// MANIPULATORS
inline
void *MultipoolAllocator::allocate(bsls::Types::size_type size)
{
return d_multipool.allocate(size);
}
inline
void MultipoolAllocator::deallocate(void *address)
{
if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(address != 0)) {
d_multipool.deallocate(address);
}
}
inline
void MultipoolAllocator::release()
{
d_multipool.release();
}
inline
void MultipoolAllocator::reserveCapacity(bsls::Types::size_type size,
int numObjects)
{
d_multipool.reserveCapacity(size, numObjects);
}
// ACCESSORS
inline
int MultipoolAllocator::numPools() const
{
return d_multipool.numPools();
}
inline
bsls::Types::size_type MultipoolAllocator::maxPooledBlockSize() const
{
return d_multipool.maxPooledBlockSize();
}
} // close package namespace
} // close enterprise namespace
#endif
// ----------------------------------------------------------------------------
// Copyright 2016 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------