bslma_newdeleteallocator.h

// bslma_newdeleteallocator.h                                         -*-C++-*-
#ifndef INCLUDED_BSLMA_NEWDELETEALLOCATOR
#define INCLUDED_BSLMA_NEWDELETEALLOCATOR

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@PURPOSE: Provide singleton new/delete adaptor to 'bslma::Allocator' protocol.
//
//@CLASSES:
//  bslma::NewDeleteAllocator: support new/delete-style allocation/deallocation
//
//@SEE_ALSO: bslma_default, bslma_testallocator
//
//@DESCRIPTION: This component provides a concrete allocation mechanism,
// 'bslma::NewDeleteAllocator', that implements the 'bslma::Allocator' protocol
// to provide direct access to the system-supplied (native) global
// 'operator new' and 'operator delete' functions via that pure abstract
// interface.
//..
//   ,-------------------------.
//  ( bslma::NewDeleteAllocator )
//   `-------------------------'
//               |         allocator
//               |         singleton
//               |         ctor/dtor
//               V
//       ,----------------.
//      ( bslma::Allocator )
//       `----------------'
//                       allocate
//                       deallocate
//..
// The essential purpose of this component is to facilitate the default use of
// global 'new' and 'delete' in all components that accept a user-supplied
// allocator derived from 'bslma::Allocator' (see 'bslma_default').  Hence, the
// global 'operator new' and 'operator delete' functions are wrapped within
// concrete methods of a derived 'bslma::NewDeleteAllocator' class.  A 'static'
// (factory) method of 'bslma::NewDeleteAllocator' can be used to obtain a
// unique (singleton) 'bslma::NewDeleteAllocator' object for the given process,
// and whose lifetime is guaranteed to exceed any possibility of its use.  Note
// that the standard also requires the global 'operator new' to return
// maximally-aligned memory, which is a stricter post condition than the
// natural-alignment requirement imposed by the base-class contract, or than is
// provided by many other concrete implementations.
//
///Thread Safety
///-------------
// This class is fully thread-safe, which means that all non-creator object
// methods can be safely accessed concurrently (from multiple treads).  The
// singleton 'bslma::NewDeleteAllocator' can also be safely created/accessed
// concurrently (from multiple threads) via either the 'static' 'singleton' or
// 'allocator' (factory) methods.  Moreover, the underlying (native)
// implementation of 'new' and 'delete' are required by the C++ standard to
// ensure that concurrent access to either the virtual 'allocate' and/or
// 'deallocate' are also safe (i.e., will not not result in heap corruption).
// Note that this allocator therefore has stronger thread-safety guarantees
// than is required by the base-class contract or than is provided by many
// other derived concrete allocators.
//
///Usage
///-----
// The most common and proper use of 'bslma::NewDeleteAllocator' is both
// *indirect* and *by* *default* (see 'bslma_default').  For example, consider
// (along with its destructor) the default and copy constructors for, say, a
// simple container, such as 'my_ShortArray', each of which take as its final
// optional argument the address of a 'bslma::Allocator' protocol:
//..
//  // my_shortarray.h:
//  // ...
//  namespace bslma { class Allocator; }
//
//  class my_ShortArray {
//      short            *d_array_p;     // dynamically-allocated array
//      int               d_capacity;    // physical capacity (in elements)
//      int               d_length;      // logical length (in elements)
//      bslma::Allocator *d_allocator_p; // memory allocator (not owned)
//
//    public:
//      my_ShortArray(bslma::Allocator *basicAllocator = 0);
//          // Create an empty 'my_shortArray'.  Optionally specify a
//          // 'basicAllocator' used to supply memory.  If 'basicAllocator'
//          // is 0, the currently installed default allocator is used.
//
//      my_ShortArray(const my_ShortArray&  other,
//                    bslma::Allocator     *basicAllocator = 0);
//          // Create a 'bslma::ShortArray' having the same value as the
//          // specified 'other' array.  Optionally specify a 'basicAllocator'
//          // used to supply memory.  If 'basicAllocator' is 0, the currently
//          // installed default allocator is used.
//
//      ~my_ShortArray();
//          // Destroy this object.
//
//     // ...
//  };
//
//  // ...
//..
// In order to satisfy this contract, we will need a globally accessible
// utility (see 'bslma_default'), which by default returns the singleton
// 'bslma::NewDeleteAllocator', but which could be configured to return some
// other allocator, say a *test* allocator (see 'bslma_testallocator'):
//..
//  // my_default.h:
//  // ...
//  namespace bslma { class Allocator; }
//
//  struct my_Default {
//      // This class maintains a process-wide 'bslma::Allocator' object
//      // to be used when an allocator is needed, and not suppled explicitly.
//      // By default, the currently installed default allocator is the unique
//      // 'bslma::NewDeleteAllocator' object returned by the 'static' method,
//      // 'bslma::NewDeleteAllocator::singleton()'.  Note that the default
//      // allocator will exist longer than any possibility of its use.
//
//      static bslma::Allocator *allocator(bslma::Allocator *basicAllocator);
//          // Return the address of the specified modifiable
//          // 'basicAllocator' or, if 'basicAllocator' is 0, an instance of
//          // the currently installed default 'bslma::Allocator' object, which
//          // will exist longer than any possibility of its use.  Note
//          // that this function can safely be called concurrently (from
//          // multiple threads).
//
//      static bslma::Allocator *replace(bslma::Allocator *basicAllocator);
//          // Replace the address of the currently installed allocator with
//          // that of the specified modifiable 'basicAllocator' (or if 0,
//          // with the "factory" default, 'bslma::NewDeleteAllocator'), and
//          // return the address of the previous allocator.  The behavior is
//          // undefined unless 'basicAllocator' will exist longer than any
//          // possibility of its use.  Note that this function is *not* *at*
//          // *all* thread-safe, and should *never* be called when multiple
//          // threads are active.
//  };
//
//  // my_default.cpp:
//  // ...
//
//  #include <my_default.h>
//
//  static bslma::Allocator *s_default_p = 0; // load-time initialized
//
//  bslma::Allocator *my_Default::allocator(bslma::Allocator *basicAllocator)
//  {
//      return bslma::NewDeleteAllocator::allocator(s_default_p);
//  }
//
//  bslma::Allocator *my_Default::replace(bslma::Allocator *basicAllocator)
//  {
//      bslma::Allocator *tmp =
//                           bslma::NewDeleteAllocator::allocator(s_default_p);
//      s_default_p = bslma::NewDeleteAllocator::allocator(basicAllocator);
//      return tmp;
//  }
//..
// Notice that the only part of the 'bslma::NewDeleteAllocator' class we used
// directly was its static 'allocator' method, which -- in addition to safely
// constructing the singleton 'bslma::NewDeleteAllocator' object on first
// access -- also automatically replaces a 0 address value with that of
// singleton 'bslma::NewDeleteAllocator' object.  From now on, we will never
// again need to invoke the 'bslma_newdeleteallocator' component's interface
// directly, but instead use it through 'my_Default' (see 'bslma::Default' for
// what is actually used in practice).
//
// Turning back to our 'my_shortarray' example, let's now implement the two
// constructors using the 'bslma_newdeleteallocator' component indirectly via
// the 'my_default' component:
//..
//  // my_shortarray.cpp:
//  #include <my_shortarray.h>
//  #include <my_default.h>
//  #include <bsls_assert.h>
//
//  // ...
//
//  enum {
//      INITIAL_CAPACITY = 0, // recommended to avoid unnecessary allocations
//                            // possibly resulting in locking and extra thread
//                            // contention for the 'bslma::NewDeleteAllocator'
//
//      GROW_FACTOR = 2       // typical value for geometric growth
//  };
//
//  // ...
//
//  my_ShortArray::my_ShortArray(bslma::Allocator *basicAllocator)
//  : d_capacity(INITIAL_CAPACITY)
//  , d_length(0)
//  , d_allocator_p(my_Default::allocator(basicAllocator))
//  {
//      assert(d_allocator_p);
//      d_array_p = (short *)  // no thread contention if 'd_capacity' is 0
//                  d_allocator_p->allocate(d_capacity * sizeof *d_array_p);
//      assert(0 == d_array_p);
//  }
//
//  my_ShortArray::my_ShortArray(const my_ShortArray&   other,
//                               bslma::Allocator      *basicAllocator)
//  : d_capacity(other.d_capacity)
//  , d_length(other.d_length)
//  , d_allocator_p(my_Default::allocator(basicAllocator))
//  {
//      assert(d_allocator_p);
//      d_array_p = (short *)
//                  d_allocator_p->allocate(d_capacity * sizeof *d_array_p);
//      assert(!d_capacity == !d_array_p);
//      memcpy(d_array_p, other.d_array_p, d_length * sizeof *d_array_p);
//  }
//
//  my_ShortArray::~my_ShortArray()
//  {
//      d_allocator_p->deallocate(d_array_p); // no locking if 'd_array_p' is 0
//  }
//
// // ...
//..
// When the default constructor is called, the default capacity and length are
// recorded in data members via the initialization list.  The static function
// 'allocator' (provided in 'my_Default') is used to assign the value of the
// 'basicAllocator' address passed in, or if that is 0, the address of the
// currently installed default allocator, which by default is the singleton
// object of type 'bslma::NewDeleteAllocator', defined in this component.  Note
// that since 'INITIAL_CAPACITY' is 0, a default constructed object that is
// created using a 'bslma::NewDeleteAllocator' will *not* invoke the
// 'operator new' function, which on some platforms may needlessly acquire a
// lock, causing unnecessary overhead (the same potential overhead is avoided
// for 'operator delete' whenever a 0 'd_array_p' value is deallocated in the
// destructor) and 'd_allocator_p' refers to a 'bslma::NewDeleteAllocator'.
// Note also that, for the copy constructor, the currently installed default
// allocator, and not the 'other' array's allocator is used whenever
// 'basicAllocator' is 0 or not explicitly supplied.
//
// Finally note that this entire component is *not* intended for direct use by
// typical clients: See 'bslma_default' for more information or proper usage.

#include <bslscm_version.h>

#include <bslma_allocator.h>

namespace BloombergLP {

namespace bslma {

                        // ========================
                        // class NewDeleteAllocator
                        // ========================

class NewDeleteAllocator : public Allocator {
    // This class defines a concrete mechanism that adapts the system-supplied
    // (native) global 'operator new' and 'operator delete' to the 'Allocator'
    // protocol.  The class method 'singleton' returns a process-wide unique
    // object of this class whose lifetime is guaranteed to extend from the
    // first call to 'singleton' until the program terminates.  A second class
    // method, 'allocator', allows for conveniently replacing a "null"
    // allocator with this singleton object.  Note that this entire class
    // should generally not be used directly by typical clients (see
    // 'bslma_default' for more information).

  private:
    // NOT IMPLEMENTED
    NewDeleteAllocator(const NewDeleteAllocator&);
    NewDeleteAllocator& operator=(const NewDeleteAllocator&);

  public:
    // CLASS METHODS
    static NewDeleteAllocator& singleton();
        // Return a reference to a process-wide unique object of this class.
        // The lifetime of this object is guaranteed to extend from the first
        // call of this method until the program terminates.  Note that this
        // method should generally not be used directly by typical clients (see
        // 'bslma_default' for more information).

    static Allocator *allocator(Allocator *basicAllocator);
        // Return the address of the specified modifiable 'basicAllocator' or,
        // if 'basicAllocator' is 0, the process-wide unique (see 'singleton')
        // object of this class.  Note that the behavior of this function is
        // equivalent to the following expression:
        //..
        //  basicAllocator
        //  ? basicAllocator
        //  : &NewDeleteAllocator::singleton()
        //..
        // Also note that if a 'NewDeleteAllocator' object is supplied, it is
        // owned by the class and must NOT be deleted.  Finally note that this
        // method should generally not be called directly by typical clients
        // (see 'bslma_default' for more information).

    // CREATORS
    NewDeleteAllocator();
        // Create a ("stateless") new-delete-allocator object that wraps the
        // global native 'operator new' and 'operator delete' functions in
        // order to supply memory via the 'Allocator' protocol.  Note that all
        // objects of this class share the same underlying resource; hence,
        // this constructor should generally not be invoked directly by
        // clients; instead, consider using the 'static' 'singleton' or
        // 'allocator' (factory) methods, or -- better -- the appropriate ones
        // in 'Default' (see 'bslma_default' for more information).

    virtual ~NewDeleteAllocator();
        // Destroy this allocator object.  Note that destroying this allocator
        // has no effect on any outstanding allocated memory.

    // MANIPULATORS
    virtual void *allocate(size_type size);
        // 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.  The alignment of the address
        // returned is the maximum alignment for any fundamental, pointer, or
        // enumerated type defined for this platform.  The behavior is
        // undefined unless '0 <= size'.  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 deallocate(void *address);
        // 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-threaded programs).
};

// ============================================================================
//                          INLINE DEFINITIONS
// ============================================================================

                        // ------------------------
                        // class NewDeleteAllocator
                        // ------------------------

// CLASS METHODS
inline
Allocator *NewDeleteAllocator::allocator(Allocator *basicAllocator)
{
    return basicAllocator ? basicAllocator : &singleton();
}

// CREATORS
inline
NewDeleteAllocator::NewDeleteAllocator()
{
}

// MANIPULATORS
inline
void 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);
    }
}

}  // close package namespace

#ifndef BDE_OPENSOURCE_PUBLICATION  // BACKWARD_COMPATIBILITY
// ============================================================================
//                           BACKWARD COMPATIBILITY
// ============================================================================

typedef bslma::NewDeleteAllocator bslma_NewDeleteAllocator;
    // This alias is defined for backward compatibility.
#endif  // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY

}  // close enterprise namespace

#endif

// ----------------------------------------------------------------------------
// Copyright 2013 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 ----------------------------------