bdlma_countingallocator.h

Go to the documentation of this file.

/// @file bdlma_countingallocator.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlma_countingallocator.h                                          -*-C++-*-
#ifndef INCLUDED_BDLMA_COUNTINGALLOCATOR
#define INCLUDED_BDLMA_COUNTINGALLOCATOR
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlma_countingallocator bdlma_countingallocator
/// @brief  Provide a memory allocator that counts allocated bytes.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlma
/// @{
/// @addtogroup bdlma_countingallocator
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlma_countingallocator-purpose"> Purpose</a>
/// * <a href="#bdlma_countingallocator-classes"> Classes </a>
/// * <a href="#bdlma_countingallocator-description"> Description </a>
///   * <a href="#bdlma_countingallocator-byte-counts"> Byte Counts </a>
///   * <a href="#bdlma_countingallocator-thread-safety"> Thread Safety </a>
///   * <a href="#bdlma_countingallocator-usage"> Usage </a>
///   * <a href="#bdlma_countingallocator-example-1-tracking-a-container-s-dynamic-memory-use"> Example 1: Tracking a Container's Dynamic Memory Use </a>
///
/// # Purpose {#bdlma_countingallocator-purpose}
/// Provide a memory allocator that counts allocated bytes.
///
/// # Classes {#bdlma_countingallocator-classes}
///
/// -  bdlma::CountingAllocator: concrete allocator that counts allocated bytes
///
/// @see  bslma_allocator, bslma_testallocator
///
/// # Description {#bdlma_countingallocator-description}
/// This component provides a special-purpose counting allocator,
/// `bdlma::CountingAllocator`, that implements the `bslma::Allocator` protocol
/// and provides instrumentation to track: (1) the number of bytes currently in
/// use (`numBytesInUse`), and (2) the cumulative number of bytes that have ever
/// been allocated (`numBytesTotal`).  The accumulated statistics are based
/// solely on the number of bytes requested in calls to the `allocate` method.
/// A `print` method is provided to output the current state of the allocator's
/// byte counts to a specified `bsl::ostream`:
/// @code
///  ,------------------------.
/// ( bdlma::CountingAllocator )
///  `------------------------'
///               |           ctor/dtor
///               |           numBytesInUse
///               |           numBytesTotal
///               |           name
///               |           print
///               V
///      ,----------------.
///     ( bslma::Allocator )
///      `----------------'
///                           allocate
///                           deallocate
/// @endcode
/// Like many other allocators, `bdlma::CountingAllocator` relies on the
/// currently installed default allocator (see @ref bslma_default ) at construction.
/// Clients may, however, override this allocator by supplying (at construction)
/// any other allocator implementing the `bslma::Allocator` protocol provided
/// that it is fully thread-safe.
///
/// Note that a `bdlma::CountingAllocator` necessarily incurs some overhead in
/// order to provide its byte-counting functionality.  However, this overhead is
/// *substantially* less than that incurred by the `bslma::TestAllocator` (see
/// @ref bslma_testallocator ), which keeps track of the same two statistics that
/// are maintained by a `bdlma::CountingAllocator`.  Consequently, use of a
/// `bdlma::CountingAllocator` may be appropriate in cases where the overhead of
/// `bslma::TestAllocator` is too onerous.  In particular, a counting allocator
/// may be suitable even for production use in certain situations, whereas the
/// test allocator is not intended for production use under any circumstance.
///
/// ## Byte Counts {#bdlma_countingallocator-byte-counts}
///
///
/// The two byte counts maintained by `bdlma::CountingAllocator` are initialized
/// to 0 at construction and increased with each call to `allocate` by `size`,
/// i.e., by the actual number of bytes requested.  Each call to `deallocate`
/// decreases the `numBytesInUse` count by the same amount by which the byte
/// count was increased in the original `allocate` call.  The number of bytes
/// currently in use is returned by `numBytesInUse` and the total number of
/// bytes ever allocated is returned by `numBytesTotal`.
///
/// ## Thread Safety {#bdlma_countingallocator-thread-safety}
///
///
/// The `bdlma::CountingAllocator` class is fully thread-safe (see
/// @ref bsldoc_glossary ) provided that the underlying allocator (established at
/// construction) is fully thread-safe.
///
/// ## Usage {#bdlma_countingallocator-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ## Example 1: Tracking a Container's Dynamic Memory Use {#bdlma_countingallocator-example-1-tracking-a-container-s-dynamic-memory-use}
///
///
/// In this example, we demonstrate how a counting allocator may be used to
/// track the amount of dynamic memory used by a container.  The container used
/// for illustration is `DoubleStack`, a stack of out-of-place `double` values.
///
/// First, we show the interface of the `DoubleStack` class:
/// @code
/// // doublestack.h
///
/// class DoubleStack {
///     // This class implements a stack of out-of-place 'double' values.
///
///     // DATA
///     double           **d_stack_p;      // dynamically allocated array of
///                                        // 'd_capacity' elements
///
///     int                d_capacity;     // physical capacity of the stack
///                                        // (in elements)
///
///     int                d_length;       // logical index of next available
///                                        // stack element
///
///     bslma::Allocator  *d_allocator_p;  // memory allocator (held, not
///                                        // owned)
///
///     // NOT IMPLEMENTED
///     DoubleStack(const DoubleStack&);
///     DoubleStack& operator=(const DoubleStack&);
///
///   private:
///     // PRIVATE MANIPULATORS
///     void increaseCapacity();
///         // Increase the capacity of this stack by at least one element.
///
///   public:
///     // CREATORS
///     explicit
///     DoubleStack(bslma::Allocator *basicAllocator = 0);
///         // Create a stack for 'double' values having an initial capacity to
///         // hold one element.  Optionally specify a 'basicAllocator' used to
///         // supply memory.  If 'basicAllocator' is 0, the currently
///         // installed default allocator is used.
///
///     ~DoubleStack();
///         // Delete this object.
///
///     // MANIPULATORS
///     void push(double value);
///         // Add the specified 'value' to the top of this stack.
///
///     void pop();
///         // Remove the element at the top of this stack.  The behavior is
///         // undefined unless this stack is non-empty.
///
///     // ACCESSORS
///     // ...
/// };
/// @endcode
/// Next, we show the (elided) implementation of `DoubleStack`.
///
/// The default constructor creates a stack having the capacity for one element
/// (the implementation of the destructor is not shown):
/// @code
/// // doublestack.cpp
/// // ...
///
/// // TYPES
/// enum { k_INITIAL_CAPACITY = 1, k_GROWTH_FACTOR = 2 };
///
/// // CREATORS
/// DoubleStack::DoubleStack(bslma::Allocator *basicAllocator)
/// : d_stack_p(0)
/// , d_capacity(k_INITIAL_CAPACITY)
/// , d_length(0)
/// , d_allocator_p(bslma::Default::allocator(basicAllocator))
/// {
///     d_stack_p = (double **)
///                    d_allocator_p->allocate(d_capacity * sizeof *d_stack_p);
/// }
/// @endcode
/// The `push` method first ensures that the array has sufficient capacity to
/// accommodate an additional value, then allocates a block in which to store
/// that value:
/// @code
/// // MANIPULATORS
/// void DoubleStack::push(double value)
/// {
///     if (d_length >= d_capacity) {
///         increaseCapacity();
///     }
///     double *stackValue = (double *)d_allocator_p->allocate(sizeof(double));
///     *stackValue = value;
///     d_stack_p[d_length] = stackValue;
///     ++d_length;
/// }
/// @endcode
/// The `pop` method asserts that the stack is not empty before deallocating the
/// block used to store the element at the top of the stack:
/// @code
/// void DoubleStack::pop()
/// {
///     BSLS_ASSERT(0 < d_length);
///
///     d_allocator_p->deallocate(d_stack_p[d_length - 1]);
///     --d_length;
/// }
/// @endcode
/// The `push` method (above) made use of the private `increaseCapacity` method,
/// which, in turn, makes use of the `reallocate` helper function (`static` to
/// the `.cpp` file).  Note that `increaseCapacity` (below) increases the
/// capacity of the `double *` array by a factor of 2 each time that it is
/// called:
/// @code
/// // HELPER FUNCTIONS
/// static
/// void reallocate(double           ***array,
///                 int                 newCapacity,
///                 int                 length,
///                 bslma::Allocator   *allocator)
///     // Reallocate memory in the specified 'array' to accommodate the
///     // specified 'newCapacity' elements using the specified 'allocator'.
///     // The specified 'length' number of leading elements are preserved.
///     // The behavior is undefined unless 'newCapacity > length'.
/// {
///     BSLS_ASSERT(newCapacity > length);
///
///     double **tmp = *array;
///     *array = (double **)allocator->allocate(newCapacity * sizeof **array);
///     bsl::memcpy(*array, tmp, length * sizeof **array);  // commit
///     allocator->deallocate(tmp);
/// }
///
/// // PRIVATE MANIPULATORS
/// void DoubleStack::increaseCapacity()
/// {
///     const int newCapacity = d_capacity * k_GROWTH_FACTOR;
///                                                     // reallocate can throw
///     reallocate(&d_stack_p, newCapacity, d_length, d_allocator_p);
///     d_capacity = newCapacity;                       // commit
/// }
/// @endcode
/// Now, we are ready to employ a `CountingAllocator` to illustrate the dynamic
/// memory use of `DoubleStack`.  We first define two constants that facilitate
/// portability of this example across 32- and 64-bit platforms:
/// @code
/// const int DBLSZ = sizeof(double);
/// const int PTRSZ = sizeof(double *);
/// @endcode
/// First, we define a `CountingAllocator`, `ca`.  At construction, a counting
/// allocator can be configured with an optional name and an optional allocator.
/// In this case, we give `ca` a name to distinguish it from other counting
/// allocators, but settle for using the default allocator:
/// @code
/// bdlma::CountingAllocator ca("'DoubleStack' Allocator");
/// @endcode
/// Next, we create a `DoubleStack`, supplying it with `ca`, and assert the
/// expected memory use incurred by the default constructor:
/// @code
/// DoubleStack stack(&ca);
///                        assert(1 * PTRSZ             == ca.numBytesInUse());
///                        assert(1 * PTRSZ             == ca.numBytesTotal());
/// @endcode
/// Next, we push an element onto the stack.  The first push incurs an
/// additional allocation to store (out-of-place) the value being inserted:
/// @code
/// stack.push(1.54);      assert(1 * PTRSZ + 1 * DBLSZ == ca.numBytesInUse());
///                        assert(1 * PTRSZ + 1 * DBLSZ == ca.numBytesTotal());
/// @endcode
/// Next, we push a second element onto the stack.  In this case, two
/// allocations result, one due to the resizing of the internal array and one
/// required to store the new value out-of-place:
/// @code
/// stack.push(0.99);      assert(2 * PTRSZ + 2 * DBLSZ == ca.numBytesInUse());
///                        assert(3 * PTRSZ + 2 * DBLSZ == ca.numBytesTotal());
/// @endcode
/// Next, we pop the top-most element from the stack.  The number of bytes in
/// use decreases by the amount used to store the popped element out-of-place:
/// @code
/// stack.pop();           assert(2 * PTRSZ + 1 * DBLSZ == ca.numBytesInUse());
///                        assert(3 * PTRSZ + 2 * DBLSZ == ca.numBytesTotal());
/// @endcode
/// Finally, we print the state of `ca` to standard output:
/// @code
/// ca.print(bsl::cout);
/// @endcode
/// which displays the following on a 32-bit platform:
/// @code
/// ----------------------------------------
///                         Counting Allocator State
/// ----------------------------------------
/// Allocator name: 'DoubleStack' Allocator
/// Bytes in use:   16
/// Bytes in total: 28
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlma
 * @{
 */
/** @addtogroup bdlma_countingallocator
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bslma_allocator.h>
 
#include <bsls_atomic.h>
#include <bsls_keyword.h>
#include <bsls_types.h>
 
#include <bsl_iosfwd.h>
 
 
namespace bdlma {
 
                         // =======================
                         // class CountingAllocator
                         // =======================
 
/// This class defines a concrete "counting" allocator mechanism that
/// implements the `bslma::Allocator` protocol, and provides instrumentation
/// to track: (1) the number of bytes currently in use, and (2) the
/// cumulative number of bytes that have ever been allocated.  The
/// accumulated statistics are based solely on the number of bytes requested
/// (see `allocate`).
///
/// Note that, like many other allocators, this allocator relies on the
/// currently installed default allocator (see @ref bslma_default ).  Clients
/// may, however, override this allocator by supplying (at construction) any
/// other allocator implementing the `bslma::Allocator` protocol provided
/// that it is fully thread-safe.
///
/// See @ref bdlma_countingallocator 
class CountingAllocator : public bslma::Allocator {
 
    // DATA
    const char        *d_name_p;         // optionally specified name of this
                                         // allocator object (or 0)
 
    bsls::AtomicInt64  d_numBytesInUse;  // number of bytes currently allocated
                                         // from this object
 
    bsls::AtomicInt64  d_numBytesTotal;  // cumulative number of bytes ever
                                         // allocated from this object
 
    bslma::Allocator  *d_allocator_p;    // memory allocator (held, not owned)
 
  private:
    // NOT IMPLEMENTED
    CountingAllocator(const CountingAllocator&);
    CountingAllocator& operator=(const CountingAllocator&);
 
  public:
    // CREATORS
 
    explicit
    CountingAllocator(bslma::Allocator *basicAllocator = 0);
    /// Create a counting allocator.  Optionally specify a `name`
    /// (associated with this object) to be included in messages output by
    /// the `print` method, thereby distinguishing this counting allocator
    /// from others that might be used in the same program.  If `name` is 0
    /// (or not specified), no distinguishing name is incorporated in
    /// `print` output.  Optionally specify a `basicAllocator` used to
    /// supply memory.  If `basicAllocator` is 0, the currently installed
    /// default allocator is used.
    explicit
    CountingAllocator(const char *name, bslma::Allocator *basicAllocator = 0);
 
    /// Destroy this allocator object.  Note that destroying this allocator
    /// has no effect on any outstanding allocated memory.
    ~CountingAllocator() BSLS_KEYWORD_OVERRIDE;
 
    // MANIPULATORS
 
    /// Return a newly-allocated block of memory of the specified `size` (in
    /// bytes).  If `size` is 0, a null pointer is returned with no other
    /// effect (e.g., on allocation statistics).  Otherwise, invoke the
    /// `allocate` method of the allocator supplied at construction, and
    /// increment the number of currently (and cumulatively) allocated bytes
    /// by `size`.
    void *allocate(bsls::Types::size_type size) BSLS_KEYWORD_OVERRIDE;
 
    /// Return the memory block at the specified `address` back to this
    /// allocator.  If `address` is 0, this function has no effect (e.g., on
    /// allocation statistics).  Otherwise, decrease the number of currently
    /// allocated bytes by the size originally requested for the block.  The
    /// behavior is undefined unless `address` was allocated using this
    /// allocator object and has not already been deallocated.
    void deallocate(void *address) BSLS_KEYWORD_OVERRIDE;
 
    // ACCESSORS
 
    /// Return the name of this counting allocator, or 0 if no name was
    /// specified at construction.
    const char *name() const;
 
    /// Return the number of bytes currently allocated from this object.
    /// Note that `numBytesInUse() <= numBytesTotal()`.
    bsls::Types::Int64 numBytesInUse() const;
 
    /// Return the cumulative number of bytes ever allocated from this
    /// object.  Note that `numBytesInUse() <= numBytesTotal()`.
    bsls::Types::Int64 numBytesTotal() const;
 
    /// Write the accumulated state information held in this allocator to
    /// the specified `stream` in some reasonable (multi-line) format, and
    /// return a reference to `stream`.
    bsl::ostream& print(bsl::ostream& stream) const;
};
 
// ============================================================================
//                             INLINE DEFINITIONS
// ============================================================================
 
                         // -----------------------
                         // class CountingAllocator
                         // -----------------------
 
// ACCESSORS
inline
const char *CountingAllocator::name() const
{
    return d_name_p;
}
 
inline
bsls::Types::Int64 CountingAllocator::numBytesInUse() const
{
    return d_numBytesInUse.loadRelaxed();
}
 
inline
bsls::Types::Int64 CountingAllocator::numBytesTotal() const
{
    return d_numBytesTotal.loadRelaxed();
}
 
}  // close package 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */