bslma_allocator

Macros
#define	bdema_Allocator   bslma::Allocator

Typedefs
typedef bslma::Allocator	bslma_Allocator
	This alias is defined for backward compatibility.

Functions
void *	operator new (std::size_t size, BloombergLP::bslma::Allocator &basicAllocator)
void	operator delete (void *address, BloombergLP::bslma::Allocator &basicAllocator)
void *	operator new (std::size_t size, BloombergLP::bslma::Allocator *basicAllocator) BSLS_KEYWORD_DELETED
	Note that this operator is intentionally not defined.
void	operator delete (void *address, BloombergLP::bslma::Allocator *basicAllocator) BSLS_KEYWORD_DELETED
	Note that this operator is intentionally not defined.

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Allocators Versus Pools
  • Overloaded Global Operators new and delete
  • Usage
    • Example 1: Container Objects
    • Example 2: Derived Concrete Allocators

Purpose

Provide a pure abstract interface for memory-allocation mechanisms.

Classes

• bslma::Allocator: protocol class for memory allocation and deallocation

See also

bslma_newdeleteallocator, bslma_testallocator

Description

This component provides the base-level protocol (pure abstract interface) class, bslma_allocator , that serves as a ubiquitous vocabulary type for various memory allocation mechanisms. The functional capabilities documented by this protocol are similar to those afforded by global operators new and delete: sufficiently (but not necessarily maximally) aligned memory is guaranteed for any object of a given size. Clients of this abstract base class will typically accept a supplied allocator (often at construction) and use its allocate and deallocate methods instead of new and delete directly.

The use of (abstract) allocators provides at least three distinct advantages over direct (hard-coded) calls to global new and delete (see bslma_newdeleteallocator ):

1. The particular choice of allocator can be selected to improve performance on a per-object basis. Without allocators, the best we can do in C++ is to overload the class-specific new and delete. Class-specific allocators tend to hoard memory even when most objects of the class have been deallocated, and often mask memory leaks that would otherwise have been detected. See Lakos-96, Section 10.3.4.2, pp 705-711.
2. By providing extra capabilities (beyond new and delete) in the derived class (see bslma_managedallocator ), we can bypass the individual destructors in a dynamically allocated type and remove all memory for one or more associated object almost instantly.
3. The bslma::Allocator protocol, like any other protocol, isolates clients from direct coupling with platform level facilities that are not fully under their control. By installing a test allocator (see bslma_testallocator ), we are able to orchestrate the white-box testing of internal calls to global operators new and delete in a platform-neutral manner.

Thread Safety

Unless otherwise documented, a single allocator object is not safe for concurrent access by multiple threads. Classes derived from bslma::Allocator that are specifically designed for concurrent access must be documented as such. Unless specifically documented otherwise, separate objects of classes derived from bslma::Allocator may safely be used in separate threads.

Allocators Versus Pools

An allocator and a pool are quite different. For starters, bslma::Allocator is an abstract class used to obtain "raw" memory of arbitrary size. A pool is a concrete data structure used to organize and supply memory according to specific needs (e.g., a consistent size). Concrete allocators may use pools in their implementations, and pools will always take a base bslma::Allocator protocol in their interface. You can think of an allocator as a stream of memory that flows into a pool of memory. Memory is allocated from the pool until it is dry; only then does new memory flow into the pool from the allocator.

Overloaded Global Operators new and delete

This component overloads the global operator new to allow convenient syntax for the construction of objects using the bslma::Allocator protocol. The overloaded new operator defined in this component has a second parameter, bslma::Allocator&, that identifies the concrete (derived) allocator that will be used to supply memory.

Consider the following use of standard placement syntax (supplied by #include <new>) along with a bslma::Allocator, used to allocate an arbitrary TYPE.

void someFunction(bslma::Allocator *basicAllocator)
{
    TYPE *obj = new (basicAllocator->allocate(sizeof(TYPE))) TYPE(...);
 
    // ...

This style of usage is inconvenient and error prone; it is also not exception safe: If the constructor of TYPE throws an exception, the basicAllocator->deallocate method is never called.

Providing an overloaded global operator new, taking a reference to a modifiable bslma::Allocator as an explicit argument allows for cleaner usage and guarantees that the basicAllocator->deallocate method is called in case of an exception:

void someFunction(bslma::Allocator *basicAllocator)
{
    TYPE *obj = new (*basicAllocator) TYPE(...);
 
    // ...

Finally, the analogous version of operator delete should not be called directly: The overloaded operator delete supplied in this component is solely for the compiler to invoke in the event an exception is thrown during a failed construction. Instead, the bslma::Allocator protocol provides deleteObject (a template member function parameterized by the type of the object being deleted), which is implemented conceptually as follows:

template <class TYPE>
void bslma::Allocator::deleteObject(TYPE *address)
{
    address->~TYPE();
    this->deallocate(address);
}

Note that there is also a deleteObjectRaw which is more efficient when it is known that the address does not refer to a secondary base class of the object being deleted.

Usage

The bslma::Allocator protocol provided in this component defines a bilateral contract between suppliers and consumers of raw memory. The following subsections illustrate (1) use, and (2) implementation of the abstract bslma::Allocator base class:

Example 1: Container Objects

Allocators are often supplied to objects requiring dynamically-allocated memory at construction. For example, consider the following my_DoubleStack class, parameterized by a bslma::Allocator:

// my_doublestack.h
// ...
 
#include <bslma_allocator.h>
 
class my_DoubleStack {
    // DATA
    double           *d_stack_p;     // dynamically allocated array (d_size
                                     // elements)
 
    int               d_size;        // physical capacity of this stack (in
                                     // elements)
 
    int               d_length;      // logical index of next available
                                     // stack element
 
    bslma::Allocator *d_allocator_p; // holds (but does not own) object
 
    // FRIENDS
    friend class my_DoubleStackIter;
 
  private:
    // PRIVATE MANIPULATORS
    void increaseSize(); // Increase the capacity by at least one element.
 
  public:
    // CREATORS
    my_DoubleStack(bslma::Allocator *basicAllocator = 0);
    my_DoubleStack(const my_DoubleStack&  other,
                   bslma::Allocator       *basicAllocator = 0);
    ~my_DoubleStack();
 
    // MANIPULATORS
    my_DoubleStack& operator=(const my_DoubleStack& rhs);
    void push(double value);
    void pop();
 
    // ACCESSORS
    const double& top() const;
    bool isEmpty() const;
};
 
// ...
 
inline
void my_DoubleStack::push(double value)
{
    if (d_length >= d_size) {
        increaseSize();
    }
    d_stack_p[d_length++] = item;
}
 
// ...

The stack interface takes an optional basicAllocator supplied only at construction. (We avoid use of the name allocator so as not to conflict with the STL use of the word, which differs slightly.) If non-zero, the stack holds a pointer to this allocator, but does not own it. If no allocator is supplied, the implementation itself must either conditionally invoke global new and delete explicitly whenever dynamic memory must be managed (BAD IDEA) or (GOOD IDEA) install a default allocator that adapts use of these global operators to the bslma_allocator interface (see bslma_newdeleteallocator ).

// my_doublestack.cpp
#include <my_doublestack.h>
#include <bslma_allocator.h>
#include <bslma_newdeleteallocator.h>  // adapter for 'new' and 'delete'
// ...
 
enum { INITIAL_SIZE = 1, GROW_FACTOR = 2 };
 
// ...
 
// CREATORS
my_DoubleStack::my_DoubleStack(bslma::Allocator *basicAllocator)
: d_size(INITIAL_SIZE)
, d_length(0)
, d_allocator_p(bslma::NewDeleteAllocator::allocator(basicAllocator))
    // The above initialization expression is equivalent to 'basicAllocator
    // ? basicAllocator : &bslma::NewDeleteAllocator::singleton()'.
{
    assert(d_allocator_p);
    d_stack_p = (double *)
                d_allocator_p->allocate(d_size * sizeof *d_stack_p);
}
 
my_DoubleStack::~my_DoubleStack()
{
    // CLASS INVARIANTS
    assert(d_allocator_p);
    assert(d_stack_p);
    assert(0 <= d_length);
    assert(0 <= d_size);
    assert(d_length <= d_size);
 
    d_allocator_p->deallocate(d_stack_p);
}

Even in this simplified implementation, all use of the allocator protocol is relegated to the .cpp file. Subsequent use of the allocator is demonstrated by the following file-scope static reallocation function:

/// Reallocate memory in the specified `array` to the specified
/// `newSize` using the specified `basicAllocator`.  The specified
/// `length` number of leading elements are preserved.  Since the
/// class invariant requires that the physical capacity of the
/// container may grow but never shrink, the behavior is undefined
/// unless `length <= newSize`.
static inline
void reallocate(double          **array,
                int               newSize,
                int               length,
                bslma::Allocator  *basicAllocator)
{
    assert(array);
    assert(1 <= newSize);
    assert(0 <= length);
    assert(basicAllocator);
    assert(length <= newSize);  // enforce class invariant
 
    double *tmp = *array;       // support exception neutrality
    *array = (double *) basicAllocator->allocate(newSize * sizeof **array);
 
    // COMMIT POINT
 
    std::memcpy(*array, tmp, length * sizeof **array);
    basicAllocator->deallocate(tmp);
}
 
// PRIVATE MANIPULATORS
void my_DoubleStack::increaseSize()
{
    int proposedNewSize = d_size * GROW_FACTOR;  // reallocate can throw
    assert(proposedNewSize > d_length);
    reallocate(&d_stack_p, proposedNewSize, d_length, d_allocator_p);
    d_size = proposedNewSize;                    // we're committed
}

Example 2: Derived Concrete Allocators

In order for the bslma::Allocator interface to be useful, we must supply a concrete allocator that implements it. In this example we demonstrate how to adapt operator new and operator delete to this protocol base class.

// my_newdeleteallocator.h
// ...
 
/// This class is a sample concrete implementation of the
/// `bslma::Allocator` protocol that provides direct access to the
/// system-supplied (native) global operators `new` and `delete`.
class my_NewDeleteAllocator : public bslma::Allocator {
 
    // NOT IMPLEMENTED
    my_NewDeleteAllocator(const bslma::NewDeleteAllocator&);
    my_NewDeleteAllocator& operator=(const bslma::NewDeleteAllocator&);
 
  public:
    // CREATORS
 
    /// Create an allocator that wraps the global (native) operators
    /// `new` and `delete` to supply memory.  Note that all objects of
    /// this class share the same underlying resource.
    my_NewDeleteAllocator();
 
    /// Destroy this allocator object.  Note that destroying this
    /// allocator has no effect on any outstanding allocated memory.
    virtual ~my_NewDeleteAllocator();
 
    // MANIPULATORS
 
    /// Return a newly allocated block of memory of (at least) the
    /// specified positive `size` (in bytes).  If `size` is 0, a null
    /// pointer is returned with no other effect.  If this allocator
    /// cannot return the requested number of bytes, then it will throw
    /// a `std::bad_alloc` exception in an exception-enabled build, or
    /// else will abort the program in a non-exception build.  The
    /// behavior is undefined unless `0 <= size`.  Note that the
    /// alignment of the address returned is the maximum alignment for
    /// any type defined on this platform.  Also note that global
    /// `operator new` is *not* called when `size` is 0 (in order to
    /// avoid having to acquire a lock, and potential contention in
    /// multi-threaded programs).
    virtual void *allocate(size_type size);
 
    /// Return the memory block at the specified `address` back to this
    /// allocator.  If `address` is 0, this function has no effect.  The
    /// behavior is undefined unless `address` was allocated using this
    /// allocator object and has not already been deallocated.  Note
    /// that global `operator delete` is *not* called when `address` is
    /// 0 (in order to avoid having to acquire a lock, and potential
    /// contention in multi-treaded programs).
    virtual void deallocate(void *address);
};
 
// CREATORS
inline
my_NewDeleteAllocator::my_NewDeleteAllocator()
{
}
// ...

The virtual methods of my_NewDeleteAllocator are defined in the component .cpp file as they would not be inlined when invoked from the base class, which would be the typical usage in this case:

// my_newdeleteallocator.cpp
#include <my_newdeleteallocator.h>
 
// CREATORS
my_NewDeleteAllocator::~my_NewDeleteAllocator()
{
}
 
// MANIPULATORS
void *my_NewDeleteAllocator::allocate(size_type size)
{
    BSLS_ASSERT_SAFE(0 <= size);
 
    return 0 == size ? 0 : ::operator new(size);
}
 
void my_NewDeleteAllocator::deallocate(void *address)
{
    // While the C++ standard guarantees that calling delete(0) is safe
    // (3.7.3.2 paragraph 3), some libc implementations take out a lock to
    // deal with the free(0) case, so this check can improve efficiency of
    // threaded programs.
 
    if (address) {
        ::operator delete(address);
    }
}

Macro Definition Documentation

bdema_Allocator

#define bdema_Allocator   bslma::Allocator

Typedef Documentation

bslma_Allocator

typedef bslma::Allocator bslma_Allocator

Function Documentation

operator delete() [1/2]

void operator delete ( void *  address, BloombergLP::bslma::Allocator &  basicAllocator  )

inline

Use the specified basicAllocator to deallocate the memory at the specified address. The behavior is undefined unless address was allocated using basicAllocator and has not already been deallocated. This operator is supplied solely to allow the compiler to arrange for it to be called in case of an exception.

operator delete() [2/2]

void operator delete	(	void *	address,
		BloombergLP::bslma::Allocator *	basicAllocator
	)

operator new() [1/2]

void * operator new ( std::size_t  size, BloombergLP::bslma::Allocator &  basicAllocator  )

inline

Return the memory allocated from the specified basicAllocator of at least the specified size bytes, or 0 if size is 0. The behavior is undefined unless 0 <= static_cast<bslma::Allocator::size_type>(size). Note that an object may allocate additional memory internally, requiring the allocator to be passed in as a constructor argument:

my_Type *createMyType(bslma::Allocator *basicAllocator)
{
    return new (*basicAllocator) my_Type(..., basicAllocator);
}

Note also that the analogous version of operator delete should not be called directly. Instead, this component provides a template member function deleteObject parameterized by TYPE that effectively performs the following operations:

void deleteMyType(bslma::Allocator *basicAllocator, my_Type *address)
{
    address->~my_Type();
    basicAllocator->deallocate(address);
}

See also deleteObjectRaw for better performance when address is known not to be a secondary base type of the object being deleted.

operator new() [2/2]

void * operator new	(	std::size_t	size,
		BloombergLP::bslma::Allocator *	basicAllocator
	)