bslma_default.h

// bslma_default.h                                                    -*-C++-*-
#ifndef INCLUDED_BSLMA_DEFAULT
#define INCLUDED_BSLMA_DEFAULT

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

//@PURPOSE: Provide utilities to set/fetch the default and global allocators.
//
//@CLASSES:
//  bslma::Default: namespace for default/global allocator management utilities
//
//@SEE_ALSO: bslma_allocator, bslma_newdeleteallocator
//
//@DESCRIPTION: This component provides a set of utility functions that manage
// the addresses of two distinguished memory allocators: the *default*
// allocator and the *global* allocator.  Each of these allocators are of type
// derived from 'bslma::Allocator'.  Note that for brevity, in the following we
// will generally refer to "the address of the default allocator" as simply
// "the default allocator" (and similarly for the global allocator).
//
// The global allocator is intended to be used as the allocator for (global)
// singleton objects.  In general, the default allocator is for all other
// memory allocations in contexts where an alternative allocator is not
// explicitly specified (or *cannot* be specified as, for example, when a
// compiler-generated temporary object of a type that requires an allocator is
// created).
//
// Initially, both the default allocator and global allocator resolve to the
// address of the 'bslma::NewDeleteAllocator' singleton, i.e.:
//..
//  &bslma::NewDeleteAllocator::singleton()
//..
// Methods are provided to retrieve and set the two allocators independently.
// The following two subsections supply further details, in turn, on the
// methods that pertain to the default and global allocators.
//
///Default Allocator
///-----------------
// Two methods provide access to the default allocator,
// 'bslma::Default::defaultAllocator' and 'bslma::Default::allocator' (the
// latter when called with no argument, or an explicit 0).  When
// 'bslma::Default::allocator' is supplied with a non-0 argument, it simply
// returns that argument to the caller, (i.e., it acts as a pass-through).  A
// (non-singleton) class that is designed to take advantage of an allocator
// will typically revert to the default allocator whenever a constructor is
// called without an allocator (yielding the default argument value of 0).  The
// 'bslma::Default::allocator' method facilitates this behavior.  See the usage
// examples below for an illustration of this technique.
//
// The default allocator can be set *prior* to a call to
// 'bslma::Default::defaultAllocator', to 'bslma::Default::allocator' with no
// argument or an explicit 0, or to 'bslma::Default::lockDefaultAllocator', by
// calling 'bslma::Default::setDefaultAllocator'.  This method returns 0 on
// success and a non-zero value on failure.  This method fails if the default
// allocator is "locked".  The default allocator is initially unlocked.  It is
// *explicitly* locked by calling 'bslma::Default::lockDefaultAllocator'.  In
// addition, the default allocator is *implicitly* locked as a *side-effect* of
// calling 'bslma::Default::defaultAllocator', or 'bslma::Default::allocator'
// with no argument or an explicit 0.  Once locked, the default allocator
// cannot be unlocked.  However, the 'bslma::Default::setDefaultAllocatorRaw'
// method will unconditionally set the default allocator regardless of whether
// it is locked.
//
// A well-behaved program should call 'bslma::Default::setDefaultAllocator'
// *once*.  It should be invoked in 'main' before starting any threads, and be
// followed immediately by a call to 'bslma::Default::lockDefaultAllocator.
// Note that 'bslma::Default::setDefaultAllocatorRaw' is provided for *testing*
// *only*, and should typically *never* be used in a production environment.
//
// *WARNING*: Note that the default allocator can become locked prior to
// entering 'main' as a side-effect of initializing a file-scope static object.
// For example, the presence of a global 'bsl::string' object in an executable
// will have this unintended consequence.  Further note that this phenomenon
// can *vary* *across* *platforms*.  In particular, linkers differ as to the
// aggressiveness with which they pull in file-scope static objects from the
// libraries that are on the link line.  *AVOID* file-scope static objects that
// require runtime initialization, *especially* those that take an allocator.
//
///Global Allocator
///----------------
// The interface pertaining to the global allocator is comparatively much
// simpler, consisting of just two methods.  The
// 'bslma::Default::globalAllocator' method, when called with no argument (or
// an explicit 0), returns the global allocator currently in effect at the
// point of call.  It has *no* side-effects.  When supplied with a non-0
// argument, 'bslma::Default::globalAllocator' simply returns that argument to
// the caller (i.e., it acts as a pass-through similar to
// 'bslma::Default::allocator' when it is supplied with a non-0 argument).  The
// global allocator may be set using the 'bslma::Default::setGlobalAllocator'
// method.  This method *always* succeeds.  In that respect, the global
// allocator cannot become locked like the default allocator.
// 'bslma::Default::setGlobalAllocator' returns the global allocator that is in
// effect upon entry to the function.
//
// Note that 'bslma::Default::setGlobalAllocator' should be used with *extreme*
// *caution*.  In particular, a well-behaved program should call this function
// at most once.  If called, it should be invoked in 'main' before starting any
// threads and before initializing singletons.
//
///Usage
///-----
// The following sequence of usage examples illustrate recommended use of the
// default and global allocators.  The examples employ the following simple
// memory allocator, 'my_CountingAllocator', that counts both the number of
// memory blocks that have been allocated, but not yet deallocated, and the
// cumulative number of blocks ever allocated.  The two values are available
// through the accessors 'numBlocksInUse' and 'numBlocksTotal', respectively.
// For actual allocations and deallocations, 'my_CountingAllocator' uses global
// operators 'new' and 'delete':
//..
//  // my_countingallocator.h
//  #include <bslma_allocator.h>
//
//  class my_CountingAllocator : public bslma::Allocator {
//      // This concrete allocator maintains: (1) a count of the number of
//      // blocks allocated that have not yet been deallocated, and (2) a count
//      // of the cumulative number of blocks ever allocated.
//
//      // DATA
//      int d_numBlocksInUse;  // number of blocks currently allocated
//      int d_numBlocksTotal;  // cumulative blocks ever requested
//
//      // NOT IMPLEMENTED
//      my_CountingAllocator(const my_CountingAllocator&);
//      my_CountingAllocator& operator=(const my_CountingAllocator&);
//
//    public:
//      // CREATORS
//      my_CountingAllocator();
//          // Create a counting allocator.
//
//      virtual ~my_CountingAllocator();
//          // Destroy this counting allocator.
//
//      // MANIPULATORS
//      virtual void *allocate(size_type size);
//          // Return a newly allocated block of memory of (at least) the
//          // specified positive 'size' (bytes).  If 'size' is 0, a null
//          // pointer is returned with no effect.  Note that the alignment of
//          // the address returned is the maximum alignment for any
//          // fundamental type defined for this platform.
//
//      virtual void deallocate(void *address);
//          // Return the memory at the specified 'address' back to this
//          // allocator.  If 'address' is 0, this function has no effect.  The
//          // behavior is undefined if 'address' was not allocated using this
//          // allocator, or has already been deallocated.
//
//      // ACCESSORS
//      int numBlocksInUse() const;
//          // Return the number of blocks currently in use from this counting
//          // allocator.
//
//      int numBlocksTotal() const;
//          // Return the cumulative number of blocks ever allocated using this
//          // counting allocator.  Note that
//          // numBlocksTotal() >= numBlocksInUse().
//  };
//
//  // CREATORS
//  inline
//  my_CountingAllocator::my_CountingAllocator()
//  : d_numBlocksInUse(0)
//  , d_numBlocksTotal(0)
//  {
//  }
//
//  // ACCESSORS
//  inline
//  int my_CountingAllocator::numBlocksInUse() const
//  {
//      return d_numBlocksInUse;
//  }
//
//  inline
//  int my_CountingAllocator::numBlocksTotal() const
//  {
//      return d_numBlocksTotal;
//  }
//..
// The 'virtual' methods of 'my_CountingAllocator' are defined in the component
// '.cpp' file:
//..
//  // my_countingallocator.cpp
//  #include <my_countingallocator.h>
//
//  // CREATORS
//  my_CountingAllocator::~my_CountingAllocator()
//  {
//  }
//
//  // MANIPULATORS
//  void *my_CountingAllocator::allocate(size_type size)
//  {
//      ++d_numBlocksInUse;
//      ++d_numBlocksTotal;
//      return ::operator new(size);
//  }
//
//  void my_CountingAllocator::deallocate(void *address)
//  {
//      --d_numBlocksInUse;
//      ::operator delete(address);
//  }
//..
//
///Example 1: Basic Default Allocator Use
/// - - - - - - - - - - - - - - - - - - -
// This usage example illustrates the basics of class design that relate to
// proper use of the default allocator, and introduces the standard pattern to
// apply when setting (and *locking*) the default allocator.  First we define a
// trivial class, 'my_Id', that uses an allocator.  'my_Id' simply encapsulates
// a C-style (null-terminated) id string that is accessible through the 'id'
// method.  Note that each constructor is declared to take an *optional*
// 'bslma::Allocator *' as its last argument.  Also note that the expression:
//..
//  bslma::Default::allocator(basicAllocator)
//..
// is used in applicable member initializers to propagate each constructor's
// allocator argument to the data members that require it (in this case, the
// object allocator that is held by each 'my_Id' object).  If 'basicAllocator'
// is 0, the object is created using the default allocator.  Otherwise, the
// explicitly supplied allocator is used:
//..
//  // my_id.h
//  #include <bslma_allocator.h>
//  #include <bslma_default.h>
//
//  class my_Id {
//      // This is a trivial class solely intended to illustrate proper use
//      // of the default allocator.
//
//      // DATA
//      char             *d_buffer_p;     // allocated (*owned*)
//      bslma::Allocator *d_allocator_p;  // allocator (held, not owned)
//
//      // NOT IMPLEMENTED (in order to reduce example size)
//      my_Id& operator=(const my_Id&);
//
//    public:
//      // CREATORS
//      explicit my_Id(const char *id, bslma::Allocator *basicAllocator = 0);
//          // Create an Id object having the specified 'id'.  Optionally
//          // specify a 'basicAllocator' used to supply memory.  If
//          // 'basicAllocator' is 0, the currently installed default allocator
//          // is used.
//
//      my_Id(const my_Id& original, bslma::Allocator *basicAllocator = 0);
//          // Create an Id object initialized to the value of the specified
//          // 'original' Id object.  Optionally specify a 'basicAllocator'
//          // used to supply memory.  If 'basicAllocator' is 0, the currently
//          // installed default allocator is used.
//
//      ~my_Id();
//          // Destroy this Id object.
//
//      // ACCESSORS
//      const char *id() const;
//          // Return the id of this Id object.
//  };
//
//  // CREATORS
//  inline
//  my_Id::my_Id(const char *id, bslma::Allocator *basicAllocator)
//  : d_allocator_p(bslma::Default::allocator(basicAllocator))
//  {
//      d_buffer_p = (char *)d_allocator_p->allocate(std::strlen(id) + 1);
//      std::strcpy(d_buffer_p, id);
//  }
//
//  inline
//  my_Id::my_Id(const my_Id& original, bslma::Allocator *basicAllocator)
//  : d_allocator_p(bslma::Default::allocator(basicAllocator))
//  {
//      const char *id = original.id();
//      d_buffer_p = (char *)d_allocator_p->allocate(std::strlen(id) + 1);
//      std::strcpy(d_buffer_p, id);
//  }
//
//  inline
//  my_Id::~my_Id()
//  {
//      d_allocator_p->deallocate(d_buffer_p);
//  }
//
//  // ACCESSORS
//  inline
//  const char *my_Id::id() const
//  {
//      return d_buffer_p;
//  }
//..
// Next we set the default allocator to one of our counting allocator objects.
// Note that immediately after successfully setting it, we lock the default
// allocator, so that subsequent calls to 'bslma::Default::setDefaultAllocator'
// fail.  (The default allocator can still be modified by calling
// 'bslma::Default::setDefaultAllocatorRaw', but calling that function in
// production code is anti-social.  Our usage examples expressly do *not* call
// that method.)  With the possible exception of test drivers, the default
// allocator should be set and locked early in 'main' before threads are
// started and before objects are initialized:
//..
//  static my_CountingAllocator defaultCountingAllocator;
//
//  int status =
//              bslma::Default::setDefaultAllocator(&defaultCountingAllocator);
//  assert(0 == status);
//  bslma::Default::lockDefaultAllocator();  // subsequent calls to "set" fail
//  assert(bslma::Default::defaultAllocator() == &defaultCountingAllocator);
//
//  status = bslma::Default::setDefaultAllocator(
//                                    &bslma::NewDeleteAllocator::singleton());
//  assert(0 != status);
//  assert(bslma::Default::defaultAllocator() == &defaultCountingAllocator);
//..
// In the following, we instantiate two objects of type 'my_Id'.  The first
// object, 'idA', is not supplied with an allocator, so it uses the default
// allocator.  The second object, 'idB', is supplied with an object of type
// 'my_CountingAllocator'.  The assertions track the states of the two
// allocators at each point in the code fragment.  In particular, note that the
// state of the default allocator does not change during the lifetime of 'idB':
//..
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(0 == defaultCountingAllocator.numBlocksTotal());
//  {
//      my_Id id("A");
//      assert(1 == defaultCountingAllocator.numBlocksInUse());
//      assert(1 == defaultCountingAllocator.numBlocksTotal());
//  }
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(1 == defaultCountingAllocator.numBlocksTotal());
//
//  my_CountingAllocator objectCountingAllocator;
//  assert(0 == objectCountingAllocator.numBlocksInUse());
//  assert(0 == objectCountingAllocator.numBlocksTotal());
//  {
//      my_Id idB("B", &objectCountingAllocator);
//      assert(1 == objectCountingAllocator.numBlocksInUse());
//      assert(1 == objectCountingAllocator.numBlocksTotal());
//      assert(0 == defaultCountingAllocator.numBlocksInUse());
//      assert(1 == defaultCountingAllocator.numBlocksTotal());
//  }
//  assert(0 == objectCountingAllocator.numBlocksInUse());
//  assert(1 == objectCountingAllocator.numBlocksTotal());
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(1 == defaultCountingAllocator.numBlocksTotal());
//..
//
///Example 2: Detecting Allocator Propagation Bugs
///- - - - - - - - - - - - - - - - - - - - - - - -
// This example demonstrates how the default allocator is used to detect a very
// common programming error pertaining to allocator usage.  First we define the
// trivial (but buggy) 'my_IdPair' class:
//..
//  // my_idpair.h
//  #include <my_id.h>
//  #include <bslma_default.h>
//
//  class my_IdPair {
//      // This is a trivial class solely intended to help illustrate a common
//      // programming error.  This class has two objects of type 'my_Id', only
//      // one of which has the allocator correctly passed to it in the
//      // definition of the constructor.
//
//      // DATA
//      my_Id d_id;     // primary id (allocating)
//      my_Id d_alias;  // alias (allocating)
//
//      // NOT IMPLEMENTED (in order to reduce example size)
//      my_IdPair(const my_IdPair&);
//      my_IdPair& operator=(const my_IdPair&);
//
//    public:
//      // CREATORS
//      my_IdPair(const char       *id,
//                const char       *alias,
//                bslma::Allocator *basicAllocator = 0);
//          // Create an Id pair having the specified 'id' and 'alias' ids.
//          // Optionally specify a 'basicAllocator' used to supply memory.  If
//          // 'basicAllocator' is 0, the currently installed default allocator
//          // is used.
//
//      ~my_IdPair();
//          // Destroy this Id pair.
//
//      // ACCESSORS
//      const char *id() const;
//          // Return the primary id of this Id pair.
//
//      const char *alias() const;
//          // Return the alias of this Id pair.
//  };
//
//  // CREATORS
//  inline
//  my_IdPair::my_IdPair(const char       *id,
//                       const char       *alias,
//                       bslma::Allocator *basicAllocator)
//  : d_id(id, bslma::Default::allocator(basicAllocator))
//  , d_alias(alias)  // drat! (forgot to pass along 'basicAllocator')
//  {
//  }
//
//  inline
//  my_IdPair::~my_IdPair()
//  {
//  }
//
//  // ACCESSORS
//  inline
//  const char *my_IdPair::id() const
//  {
//      return d_id.id();
//  }
//
//  inline
//  const char *my_IdPair::alias() const
//  {
//      return d_alias.id();
//  }
//..
// The definition of the 'my_IdPair' constructor above intentionally includes a
// common programming error: The allocator in use by the object is not passed
// to *all* data members that require it.  We will see shortly how this error
// is detected at runtime using the default allocator.
//
// Next, the default allocator is set and locked identically to what was done
// in usage example 1:
//..
//  static my_CountingAllocator defaultCountingAllocator;
//
//  int status =
//              bslma::Default::setDefaultAllocator(&defaultCountingAllocator);
//  assert(0 == status);
//  bslma::Default::lockDefaultAllocator();
//  assert(bslma::Default::defaultAllocator() == &defaultCountingAllocator);
//..
// Now we instantiate an object of type 'my_IdPair' without explicitly
// specifying an allocator.  As a result, the object uses the default
// allocator.  The assertions verify the expected changes in the state of the
// default allocator:
//..
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(0 == defaultCountingAllocator.numBlocksTotal());
//  {
//      my_IdPair idPair("A", "B");
//      assert(2 == defaultCountingAllocator.numBlocksInUse());
//      assert(2 == defaultCountingAllocator.numBlocksTotal());
//  }
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(2 == defaultCountingAllocator.numBlocksTotal());
//..
// Next we instantiate a second object of type 'my_IdPair', this time supplying
// it with a counting allocator object that is distinct from the default
// allocator.  The assertions in the following code fragment that are commented
// out indicate the *expected* states of the allocators (i.e., in a bug-free
// implementation of 'my_IdPair') after the object has been constructed and
// again after it has been destroyed.  However, due to the (intentional) bug in
// the constructor, the uncommented assertions reveal the *true* state of
// affairs:
//..
//  my_CountingAllocator objectCountingAllocator;
//  assert(0 == objectCountingAllocator.numBlocksInUse());
//  assert(0 == objectCountingAllocator.numBlocksTotal());
//  {
//      my_IdPair idPair("X", "Y", &objectCountingAllocator);
//      // assert(2 == objectCountingAllocator.numBlocksInUse());
//      // assert(2 == objectCountingAllocator.numBlocksTotal());
//      // assert(0 == defaultCountingAllocator.numBlocksInUse());
//      // assert(2 == defaultCountingAllocator.numBlocksTotal());
//      assert(1 == objectCountingAllocator.numBlocksInUse());
//      assert(1 == objectCountingAllocator.numBlocksTotal());
//      assert(1 == defaultCountingAllocator.numBlocksInUse());
//      assert(3 == defaultCountingAllocator.numBlocksTotal());
//  }
//  // assert(0 == objectCountingAllocator.numBlocksInUse());
//  // assert(2 == objectCountingAllocator.numBlocksTotal());
//  // assert(0 == defaultCountingAllocator.numBlocksInUse());
//  // assert(2 == defaultCountingAllocator.numBlocksTotal());
//  assert(0 == objectCountingAllocator.numBlocksInUse());
//  assert(1 == objectCountingAllocator.numBlocksTotal());
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(3 == defaultCountingAllocator.numBlocksTotal());
//..
// Note that, although not necessary in the case of the simple 'my_IdPair'
// class, the default allocator can be used (and typically *should* be used)
// within the body of a constructor, or any other member function, to allocate
// dynamic memory that is *temporarily* needed by the method (and, hence, not
// owned by the object after the method has returned).  Thus, the invariant
// that must hold immediately after a method of an object returns is that the
// value returned by 'defaultCountingAllocator.numBlocksInUse()' must be
// *identical* to what it was immediately prior to calling the method.  Of
// course, note that the above invariant pertains to cases in *single*-threaded
// programs where the object allocator in use by the object is *distinct* from
// the default allocator.  Also note that the value returned by
// 'defaultCountingAllocator.numBlocksTotal()' *can* differ across function
// invocations (i.e., even in correct code).
//
///Example 3: Basic Global Allocator Use
///- - - - - - - - - - - - - - - - - - -
// Next we define a simple singleton class, 'my_Singleton', that defaults to
// using the global allocator if one is not explicitly specified when the
// singleton object is initialized.  Toward that end, note that in contrast to
// 'my_Id', the constructor for 'my_Singleton' uses:
//..
//  bslma::Default::globalAllocator(basicAllocator)
//..
// in its member initializer:
//..
//  // my_singleton.h
//  class my_Singleton {
//      // This is a trivial singleton class solely intended to illustrate use
//      // of the global allocator.
//
//      // CLASS DATA
//      static my_Singleton *s_singleton_p;  // pointer to singleton object
//
//      // PRIVATE DATA
//      my_Id d_id;  // allocating
//
//      // NOT IMPLEMENTED
//      my_Singleton(const my_Singleton&  original,
//                   bslma::Allocator    *basicAllocator = 0);
//      my_Singleton& operator=(const my_Singleton& rhs);
//
//    private:
//      // PRIVATE CREATORS
//      explicit my_Singleton(const char       *id,
//                            bslma::Allocator *basicAllocator = 0);
//          // Create a singleton having the specified 'id'.  Optionally
//          // specify a 'basicAllocator' used to supply memory.  If
//          // 'basicAllocator' is 0, the currently installed global allocator
//          // is used.
//
//      ~my_Singleton();
//          // Destroy this singleton.
//
//    public:
//      // CLASS METHODS
//      static void initSingleton(const char       *id,
//                                bslma::Allocator *basicAllocator = 0);
//          // Initialize the singleton with the specified 'id'.  Optionally
//          // specify a 'basicAllocator' used to supply memory.  If
//          // 'basicAllocator' is 0, the currently installed global allocator
//          // is used.
//
//      static const my_Singleton& singleton();
//          // Return a reference to the non-modifiable singleton of this
//          // class.  The behavior is undefined unless the singleton has been
//          // initialized.
//
//      // ACCESSORS
//      const char *id() const;
//          // Return the id of this singleton.
//  };
//
//  // CLASS METHODS
//  inline
//  const my_Singleton& my_Singleton::singleton()
//  {
//      return *s_singleton_p;
//  }
//
//  // CREATORS
//  inline
//  my_Singleton::my_Singleton(const char *id,
//                             bslma::Allocator *basicAllocator)
//  : d_id(id, bslma::Default::globalAllocator(basicAllocator))
//  {
//  }
//
//  inline
//  my_Singleton::~my_Singleton()
//  {
//  }
//
//  // ACCESSORS
//  inline
//  const char *my_Singleton::id() const
//  {
//      return d_id.id();
//  }
//..
// The following completes the definition of 'my_Singleton' in the component
// '.cpp' file:
//..
//  // my_singleton.cpp
//  #include <my_singleton.h>
//  #include <bsls_alignedbuffer.h>
//
//  my_Singleton *my_Singleton::s_singleton_p;
//
//  // CLASS METHODS
//  void my_Singleton::initSingleton(const char       *id,
//                                   bslma::Allocator *basicAllocator)
//  {
//      static bsls::AlignedBuffer<sizeof(my_Singleton)> singleton;
//      s_singleton_p = new (singleton.buffer()) my_Singleton(id,
//                                                            basicAllocator);
//  }
//..
// In the following, the default and global allocators are set to distinct
// instances of 'my_CountingAllocator'.  Note that the default allocator is set
// and locked identically to what was done in the previous two usage examples:
//..
//  static my_CountingAllocator defaultCountingAllocator;
//
//  int status = bslma::Default::setDefaultAllocator(
//                                                  &defaultCountingAllocator);
//  assert(0 == status);
//  bslma::Default::lockDefaultAllocator();
//  assert(bslma::Default::defaultAllocator() == &defaultCountingAllocator);
//
//  static my_CountingAllocator globalCountingAllocator;
//
//  bslma::Default::setGlobalAllocator(&globalCountingAllocator);
//  assert(bslma::Default::globalAllocator() == &globalCountingAllocator);
//..
// Finally, we initialize the singleton object.  We explicitly specify the
// desired allocator in the call to 'initSingleton' to make our intentions as
// clear as possible.  Of course, because of the way the 'my_Singleton'
// constructor was written, the result would have been the same if no allocator
// had been specified.  As in previous examples, the states of the default and
// global allocators are asserted before and after initializing the singleton:
//..
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(0 == defaultCountingAllocator.numBlocksTotal());
//  assert(0 == globalCountingAllocator.numBlocksInUse());
//  assert(0 == globalCountingAllocator.numBlocksTotal());
//
//  my_Singleton::initSingleton("S", bslma::Default::globalAllocator());
//
//  assert(0 == defaultCountingAllocator.numBlocksInUse());
//  assert(0 == defaultCountingAllocator.numBlocksTotal());
//  assert(1 == globalCountingAllocator.numBlocksInUse());
//  assert(1 == globalCountingAllocator.numBlocksTotal());
//..

#include <bslscm_version.h>

#include <bsls_atomicoperations.h>

#include <bslma_newdeleteallocator.h>

namespace BloombergLP {

namespace bslma {

class Allocator;

                        // ==============
                        // struct Default
                        // ==============

struct Default {
    // This struct is a mechanism with global state, i.e., all state is held in
    // global variables and all functions are class methods.  The state
    // consists of two distinct parts that don't influence one another: the
    // default allocator and the global allocator.  All addresses are stored
    // without assuming ownership.
    //
    // The 'setDefaultAllocator' method will only modify the default allocator
    // prior to the default allocator being accessed (by either 'allocator',
    // 'defaultAllocator', or 'lockDefaultAllocator'). The global allocator may
    // be freely modified.
    //
    // Note that *only* the *owner* of 'main' (or in *testing*), where the
    // caller affirmatively takes responsibility for the behavior of all
    // clients of the global allocator, is intended to change the global
    // allocator.

  private:
    // CLASS DATA

                        // *** default allocator ***

    static bsls::AtomicOperations::AtomicTypes::Pointer
                                                   s_requestedDefaultAllocator;
        // The default allocator that is requested by the user and will be
        // installed as the default allocator on the first attempt to access
        // the default allocator (via 'allocator', 'defaultAllocator', or
        // 'lockDefaultAllocator').  This value is initialized to '0',
        // indicating the user hasn't made a choice yet.  In that case, when
        // needed, the new-delete allocator will be used.  This value can be
        // set (multiple times) by calling to 'setDefaultAllocator'.  Note that
        // once changed this variable will not become '0' again.

    static bsls::AtomicOperations::AtomicTypes::Pointer s_defaultAllocator;
        // The currently installed default allocator.  This variable must be
        // set only once, when the default allocator is first accessed (via
        // 'allocator', 'defaultAllocator', or 'lockDefaultAllocator') but may
        // be '0' before it is accessed unless *for* *testing* *only*
        // 'setDefaultAllocatorRaw' is used.

                        // *** global allocator ***

    static bsls::AtomicOperations::AtomicTypes::Pointer s_globalAllocator;
        // The address of the global allocator to use.

    // PRIVATE CLASS METHODS
    static Allocator *determineAndReturnDefaultAllocator();
        // Return the address of the default allocator and disable all
        // subsequent calls to the 'setDefaultAllocator' method.  If
        // 's_defaultAllocator' is 0 (meaning the default allocator has not yet
        // been accessed), set it to the last value supplied to
        // 'setDefaultAllocator' (stored in 's_requestedDefaultAllocator').  If
        // 's_requestedDefaultAllocator' is 0 (meaning 'setDefaultAllocator'
        // has not been called) set 's_defaultAllocator' and
        // 's_requestedDefaultAllocator' to be the new-delete allocator.  Note
        // that this operation performs the one and only assigment to
        // 's_defaultAllocator' (unless 'setDefaultllocatorRaw' is called).
        // Note also that this function has the same externally visible
        // behavior as 'defaultAllocator', but forms the (thread-safe)
        // "slow-path" for that function's implementation.

  public:
    // CLASS METHODS

                        // *** default allocator ***

    static int setDefaultAllocator(Allocator *basicAllocator);
        // Set the address of the default allocator to the specified
        // 'basicAllocator' unless calls to this method have been disabled.
        // Return 0 on success and a non-zero value otherwise.  This method
        // will fail if either 'defaultAllocator', 'lockDefaultAllocator', or
        // 'allocator' with argument 0 has been called previously in this
        // process.  The behavior is undefined unless 'basicAllocator' is the
        // address of an allocator with sufficient lifetime to satisfy all
        // allocation requests within this process, and unless there is only
        // one thread started within this process.  Note that this method is
        // intended for use *only* by the *owner* of 'main' (or for use in
        // *testing*) where the caller affirmatively takes responsibility for
        // the behavior of all clients of the default allocator, and should
        // *not* be used for any other purpose.

    static void setDefaultAllocatorRaw(Allocator *basicAllocator);
        // Unconditionally set the address of the default allocator to the
        // specified 'basicAllocator'.  The behavior is undefined unless
        // 'basicAllocator' is the address of an allocator with sufficient
        // lifetime to satisfy all allocation requests within this process, and
        // unless there is only one thread started within this process.  Note
        // that this method is intended for use *only* in *testing* where the
        // caller affirmatively takes responsibility for the behavior of all
        // clients of the default allocator, and should *not* be used for any
        // other purpose.

    static void lockDefaultAllocator();
        // Disable all subsequent calls to the 'setDefaultAllocator' method.
        // Subsequent calls to this method have no effect.  Note that
        // subsequent calls to the 'setDefaultAllocatorRaw' method are *not*
        // disabled by this method.

    static Allocator *defaultAllocator();
        // Return the address of the default allocator and disable all
        // subsequent calls to the 'setDefaultAllocator' method.  Note that
        // prior to the first call to 'setDefaultAllocator' or
        // 'setDefaultAllocatorRaw' methods, the address of the default
        // allocator is that of the 'NewDeleteAllocator' singleton.  Also note
        // that subsequent calls to 'setDefaultAllocatorRaw' method are *not*
        // disabled by this method.

    static Allocator *allocator(Allocator *basicAllocator = 0);
        // Return the allocator returned by 'defaultAllocator' and disable all
        // subsequent calls to the 'setDefaultAllocator' method if the
        // optionally-specified 'basicAllocator' is 0; return 'basicAllocator'
        // otherwise.

                        // *** global allocator ***

    static Allocator *globalAllocator(Allocator *basicAllocator = 0);
        // Return the address of the global allocator if the optionally-
        // specified 'basicAllocator' is 0, and 'basicAllocator' otherwise.
        // Note that prior to the first call to the 'setGlobalAllocator'
        // method, the address of the global allocator is that of the
        // 'NewDeleteAllocator' singleton.

    static Allocator *setGlobalAllocator(Allocator *basicAllocator);
        // Unconditionally set the address of the global allocator to the
        // specified 'basicAllocator', or to the address of the
        // 'NewDeleteAllocator' singleton if 'basicAllocator' is 0.  Return the
        // address of the global allocator in effect immediately before calling
        // this method.  The behavior is undefined unless 'basicAllocator' is 0
        // or is the address of an allocator with sufficient lifetime to
        // satisfy all global allocation requests within this process, and
        // unless there is only one thread started within this process.  Note
        // that prior to the first call to this method, the address of the
        // global allocator is that of the 'NewDeleteAllocator' singleton.
        // Also note that this method is intended for use *only* by the *owner*
        // of 'main' (or for use in *testing*) where the caller affirmatively
        // takes responsibility for the behavior of all clients of the global
        // allocator, and should *not* be used for any other purpose.
};

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

                        // --------------
                        // struct Default
                        // --------------

// CLASS METHODS

                        // *** default allocator ***

inline
void Default::lockDefaultAllocator()
{
    determineAndReturnDefaultAllocator();
}

inline
Allocator *Default::defaultAllocator()
{
    void *alloc = bsls::AtomicOperations::getPtrRelaxed(&s_defaultAllocator);
    return alloc ? static_cast<Allocator *>(alloc)
                 : determineAndReturnDefaultAllocator();
}

inline
Allocator *Default::allocator(Allocator *basicAllocator)
{
    return basicAllocator ? basicAllocator : defaultAllocator();
}

                        // *** global allocator ***

inline
Allocator *Default::globalAllocator(Allocator *basicAllocator)
{
    Allocator *globalAllocator = static_cast<Allocator *>(const_cast<void *>(
                   bsls::AtomicOperations::getPtrAcquire(&s_globalAllocator)));

    return basicAllocator ? basicAllocator
                          : globalAllocator
                                      ? globalAllocator
                                      : &NewDeleteAllocator::singleton();
}

}  // close package namespace

#ifndef BDE_OPENSOURCE_PUBLICATION  // BACKWARD_COMPATIBILITY

// ============================================================================
//                           BACKWARD COMPATIBILITY
// ============================================================================

#ifndef BDE_OMIT_INTERNAL_DEPRECATED
                        // ====================
                        // struct bdema_Default
                        // ====================

typedef bslma::Default bdema_Default;
    // This 'struct' is a namespace for functions that manipulate and access
    // the default and global allocator pointers.  This alias is defined for
    // backward compatibility.

#endif // BDE_OMIT_INTERNAL_DEPRECATED

typedef bslma::Default bslma_Default;
    // 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 ----------------------------------