bslma.h

Go to the documentation of this file.

/// @file bslma.h
///
///
/// @defgroup bslma Package bslma
/// @brief  Basic Standard Library Memory Allocators (bslma)
/// @addtogroup bsl
/// @{
/// @addtogroup bslma
/// @{
/// * <a href="#bslma-purpose"> Purpose</a>
/// * <a href="#bslma-mnemonic"> Mnemonic </a>
/// * <a href="#bslma-description"> Description </a>
///   * <a href="#bslma-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bslma-component-synopsis"> Component Synopsis </a>
///   * <a href="#bslma-component-overview"> Component Overview </a>
///     * <a href="#bslma-bslma_allocator"> bslma_allocator </a>
///     * <a href="#bslma-bslma_autodeallocator"> bslma_autodeallocator </a>
///     * <a href="#bslma-bslma_autodestructor"> bslma_autodestructor </a>
///     * <a href="#bslma-bslma_autorawdeleter"> bslma_autorawdeleter </a>
///     * <a href="#bslma-bslma_deallocatorguard"> bslma_deallocatorguard </a>
///     * <a href="#bslma-bslma_deallocatorproctor"> bslma_deallocatorproctor </a>
///     * <a href="#bslma-bslma_default"> bslma_default </a>
///     * <a href="#bslma-bslma_defaultallocatorguard"> bslma_defaultallocatorguard </a>
///     * <a href="#bslma-bslma_deleterhelper"> bslma_deleterhelper </a>
///     * <a href="#bslma-bslma_destructorguard"> bslma_destructorguard </a>
///     * <a href="#bslma-bslma_destructorproctor"> bslma_destructorproctor </a>
///     * <a href="#bslma-bslma_isstdallocator"> bslma_isstdallocator </a>
///     * <a href="#bslma-bslma_mallocfreeallocator"> bslma_mallocfreeallocator </a>
///     * <a href="#bslma-bslma_newdeleteallocator"> bslma_newdeleteallocator </a>
///     * <a href="#bslma-bslma_rawdeleterguard"> bslma_rawdeleterguard </a>
///     * <a href="#bslma-bslma_rawdeleterproctor"> bslma_rawdeleterproctor </a>
///     * <a href="#bslma-bslma_testallocator"> bslma_testallocator </a>
///     * <a href="#bslma-bslma_testallocatorexception"> bslma_testallocatorexception </a>
///     * <a href="#bslma-bslma_testallocatormonitor"> bslma_testallocatormonitor </a>
///   * <a href="#bslma-why-use-allocators"> Why Use Allocators </a>
///   * <a href="#bslma-rationale-for-the-bde-allocator-model"> Rationale for the BDE Allocator Model </a>
///   * <a href="#bslma-allocators-and-other-memory-dispensing-mechanisms"> Allocators and Other Memory-Dispensing Mechanisms </a>
///   * <a href="#bslma-allocator-and-managedallocator"> Allocator and ManagedAllocator </a>
///   * <a href="#bslma-proctors-and-guards"> Proctors and Guards </a>
///   * <a href="#bslma-alignment"> Alignment </a>
///   * <a href="#bslma-deallocation"> Deallocation </a>
///   * <a href="#bslma-type-and-origination"> Type and Origination </a>
///   * <a href="#bslma-the-default-allocator"> The Default Allocator </a>
///   * <a href="#bslma-interaction-with-other-packages"> Interaction With Other Packages </a>
///   * <a href="#bslma-usage"> Usage </a>
///     * <a href="#bslma-example-1-creating-a-type-that-uses-bslma-allocator"> Example 1: Creating a type that uses bslma::Allocator </a>
///     * <a href="#bslma-example-2-implementing-templates-that-may-be-supplied-allocating-types"> Example 2: Implementing Templates That May Be Supplied Allocating Types </a>
///     * <a href="#bslma-example-3-implementing-a-customized-allocator"> Example 3: Implementing a Customized Allocator </a>
///
/// # Purpose {#bslma-purpose}
/// Provide allocators, guards, and other memory-management tools.
///
/// # Mnemonic {#bslma-mnemonic}
/// Basic Standard Library Memory Allocators (bslma)
///
/// # Description {#bslma-description}
/// The 'bslma' package provides an allocator protocol (i.e., a pure
/// abstract interface) and a variety of concrete allocators derived from this
/// protocol, as well as other memory-dispensing mechanisms and various guard
/// constructs to prevent loss in case of exceptions.  In addition, 'bslma' also
/// provides a mechanism for installing a "default allocator" that will then be
/// visible to all BDE and BDE-compliant code throughout that process.  If this
/// mechanism is not invoked explicitly, then an allocator that uses global 'new'
/// and 'delete' is the BDE default allocator.  This topic is discussed in more
/// detail below.
///
/// ## Hierarchical Synopsis {#bslma-hierarchical-synopsis}
///
/// The 'bslma' package currently has 59 components having 16 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  16. bslma_managedptr
///
///  15. bslma_autodeallocator
///      bslma_destructorproctor
///
///  14. bslma_deallocatorproctor                           !DEPRECATED!
///
///  13. bslma_aatypeutil
///      bslma_deallocatebytesproctor
///      bslma_deallocateobjectproctor
///      bslma_deleteobjectproctor
///
///  12. bslma_aamodel
///      bslma_allocatorutil
///      bslma_stdallocator                                 !DEPRECATED!
///
///  11. bslma_bslallocator
///
///  10. bslma_polymorphicallocator
///
///   9. bslma_allocatortraits
///      bslma_managedptr_factorydeleter                                 !PRIVATE!
///      bslma_managedptr_members                                        !PRIVATE!
///      bslma_sequentialallocator                          !DEPRECATED!
///      bslma_stdtestallocator
///
///   8. bslma_constructionutil
///      bslma_sequentialpool                               !DEPRECATED!
///      bslma_sharedptrinplacerep
///      bslma_sharedptroutofplacerep
///      bslma_testallocatormonitor
///      bslma_testallocatorstatisticsguard
///
///   7. bslma_allocatoradaptor
///      bslma_autodestructor
///      bslma_deallocatorguard
///      bslma_defaultallocatorguard
///      bslma_destructionutil
///      bslma_destructorguard
///      bslma_exceptionguard
///      bslma_infrequentdeleteblocklist                    !DEPRECATED!
///      bslma_managedptr_pairproxy                                      !PRIVATE!
///      bslma_managedptrdeleter
///      bslma_rawdeleterguard
///      bslma_rawdeleterproctor
///      bslma_sharedptrrep
///
///   6. bslma_default
///      bslma_testallocator
///
///   5. bslma_autorawdeleter
///      bslma_bufferallocator                              !DEPRECATED!
///      bslma_mallocfreeallocator
///      bslma_managedallocator                             !DEPRECATED!
///      bslma_newdeleteallocator
///      bslma_testallocatorexception
///      bslma_usesbslmaallocator
///
///   4. bslma_allocator
///
///   3. bslma_hasallocatortype
///      bslma_memoryresourceimpsupport
///
///   2. bslma_allocatortraits_cpp03                                     !PRIVATE!
///      bslma_deleterhelper
///      bslma_isstdallocator
///      bslma_memoryresource
///      bslma_polymorphicallocator_cpp03                                !PRIVATE!
///
///   1. bslma_allocatorutil_cpp03                                       !PRIVATE!
///      bslma_bslallocator_cpp03                                        !PRIVATE!
///      bslma_constructionutil_cpp03                                    !PRIVATE!
///      bslma_managedptr_cpp03                                          !PRIVATE!
///      bslma_sharedptrinplacerep_cpp03                                 !PRIVATE!
/// @endcode
///
/// ## Component Synopsis {#bslma-component-synopsis}
///
///  @ref bslma_aamodel :
///       Provide metafunctions to detect a type's allocator-awareness model.
/// 
///  @ref bslma_aatypeutil :
///       Provide a namespace for utility functions on allocator-aware types.
/// 
///  @ref bslma_allocator :
///       Provide a pure abstract interface for memory-allocation mechanisms.
/// 
///  @ref bslma_allocatoradaptor :
///       Provide a polymorphic adaptor for STL-style allocators
/// 
///  @ref bslma_allocatortraits :
///       Provide a uniform interface to standard allocator types.
/// 
///  @ref bslma_allocatortraits_cpp03 :                                      !PRIVATE!
///       Provide C++03 implementation for bslma_allocatortraits.h
/// 
///  @ref bslma_allocatorutil :
///       Provide a namespace for utility functions on allocators.
/// 
///  @ref bslma_allocatorutil_cpp03 :                                        !PRIVATE!
///       Provide C++03 implementation for bslma_allocatorutil.h
/// 
///  @ref bslma_autodeallocator :
///       Provide a range proctor to managed a block of memory.
/// 
///  @ref bslma_autodestructor :
///       Provide a range proctor to manage an array of objects.
/// 
///  @ref bslma_autorawdeleter :
///       Provide a range proctor to manage a sequence objects.
/// 
///  @ref bslma_bslallocator :
///       Provide an STL-compatible proxy for `bslma::Allocator` objects.
/// 
///  @ref bslma_bslallocator_cpp03 :                                         !PRIVATE!
///       Provide C++03 implementation for bslma_bslallocator.h
/// 
///  @ref bslma_bufferallocator :                               !DEPRECATED!
///       Support efficient memory allocations from a user-supplied buffer.
/// 
///  @ref bslma_constructionutil :
///       Provide methods to construct arbitrarily-typed objects uniformly.
/// 
///  @ref bslma_constructionutil_cpp03 :                                     !PRIVATE!
///       Provide C++03 implementation for bslma_constructionutil.h
/// 
///  @ref bslma_deallocatebytesproctor :
///       Provide a proctor to conditionally unwind memory block allocation.
/// 
///  @ref bslma_deallocateobjectproctor :
///       Provide a proctor to conditionally unwind object allocation.
/// 
///  @ref bslma_deallocatorguard :
///       Provide a guard to unconditionally manage a block of memory.
/// 
///  @ref bslma_deallocatorproctor :                            !DEPRECATED!
///       Provide a proctor to conditionally manage a block memory.
/// 
///  @ref bslma_default :
///       Provide utilities to set/fetch the default and global allocators.
/// 
///  @ref bslma_defaultallocatorguard :
///       Provide scoped guard to temporarily change the default allocator.
/// 
///  @ref bslma_deleteobjectproctor :
///       Provide a proctor to conditionally unwind new object creation.
/// 
///  @ref bslma_deleterhelper :
///       Provide namespace for functions used to delete objects.
/// 
///  @ref bslma_destructionutil :
///       Provide routines that destroy objects efficiently.
/// 
///  @ref bslma_destructorguard :
///       Provide a guard to unconditionally manage an object.
/// 
///  @ref bslma_destructorproctor :
///       Provide a proctor to conditionally manage an object.
/// 
///  @ref bslma_exceptionguard :
///       Provide a check that objects throwing exceptions do not change.
/// 
///  @ref bslma_hasallocatortype :
///       Provide a compile-time check for an `allocator_type` typedef
/// 
///  @ref bslma_infrequentdeleteblocklist :                     !DEPRECATED!
///       Provide allocation and management of a sequence of memory blocks.
/// 
///  @ref bslma_isstdallocator :
///       Provide a compile-time check for determining allocator types.
/// 
///  @ref bslma_mallocfreeallocator :
///       Provide malloc/free adaptor to `bslma::Allocator` protocol.
/// 
///  @ref bslma_managedallocator :                              !DEPRECATED!
///       Provide a protocol for memory allocators that support `release`.
/// 
///  @ref bslma_managedptr :
///       Provide a managed pointer class.
/// 
///  @ref bslma_managedptr_cpp03 :                                           !PRIVATE!
///       Provide C++03 implementation for bslma_managedptr.h
/// 
///  @ref bslma_managedptr_factorydeleter :                                  !PRIVATE!
///       Provide a factory-based deleter for the managed pointer class.
/// 
///  @ref bslma_managedptr_members :                                         !PRIVATE!
///       Provide the internal state of a managed pointer class.
/// 
///  @ref bslma_managedptr_pairproxy :                                       !PRIVATE!
///       Provide the internal state of a managed pointer class.
/// 
///  @ref bslma_managedptrdeleter :
///       Provide an in-core value-semantic class to call a delete function.
/// 
///  @ref bslma_memoryresource :
///       Provide a pure abstract interface for memory-allocation mechanisms.
/// 
///  @ref bslma_memoryresourceimpsupport :
///       Provide support for implementing memory resources
/// 
///  @ref bslma_newdeleteallocator :
///       Provide singleton new/delete adaptor to `bslma::Allocator` protocol.
/// 
///  @ref bslma_polymorphicallocator :
///       Provide an allocator interface for `bsl::memory_resource` objects.
/// 
///  @ref bslma_polymorphicallocator_cpp03 :                                 !PRIVATE!
///       Provide C++03 implementation for bslma_polymorphicallocator.h
/// 
///  @ref bslma_rawdeleterguard :
///       Provide a guard to unconditionally manage an object.
/// 
///  @ref bslma_rawdeleterproctor :
///       Provide a proctor to conditionally manage an object.
/// 
///  @ref bslma_sequentialallocator :                           !DEPRECATED!
///       Support fast memory allocation for objects of varying sizes.
/// 
///  @ref bslma_sequentialpool :                                !DEPRECATED!
///       Provide fast variable-size memory pool with allocation methods.
/// 
///  @ref bslma_sharedptrinplacerep :
///       Provide an in-place implementation of `bslma::SharedPtrRep`.
/// 
///  @ref bslma_sharedptrinplacerep_cpp03 :                                  !PRIVATE!
///       Provide C++03 implementation for bslma_sharedptrinplacerep.h
/// 
///  @ref bslma_sharedptroutofplacerep :
///       Provide an out-of-place implementation of `bslma::SharedPtrRep`.
/// 
///  @ref bslma_sharedptrrep :
///       Provide an abstract class for a shared object manager.
/// 
///  @ref bslma_stdallocator :                                  !DEPRECATED!
///       Provide an STL-compatible proxy for `bslma::Allocator` objects.
/// 
///  @ref bslma_stdtestallocator :
///       Provide stl-compatible, `bslma`-style allocator to track usage.
/// 
///  @ref bslma_testallocator :
///       Provide instrumented malloc/free allocator to track memory usage.
/// 
///  @ref bslma_testallocatorexception :
///       Provide an exception class for memory allocation operations.
/// 
///  @ref bslma_testallocatormonitor :
///       Provide a mechanism to summarize `bslma::TestAllocator` object use.
/// 
///  @ref bslma_testallocatorstatisticsguard :
///       Provide mechanism for `bslma::TestAllocator` scoped statistics.
/// 
///  @ref bslma_usesbslmaallocator :
///       Provide a metafunction to indicate the use of `bslma` allocators.
/// ## Component Overview {#bslma-component-overview}
///
/// This section provides a brief introduction to some of the components of the
/// 'bslma' package.  See the documentation in each component for full details.
///
/// ### bslma_allocator {#bslma-bslma_allocator}
///
/// The @ref bslma_allocator  component defines a protocol (i.e., an abstract base
/// class) requiring the following interface: `allocate` for memory allocation,
/// and `deallocate`, for allocation and deallocation of individual memory blocks.
///
/// ### bslma_autodeallocator {#bslma-bslma_autodeallocator}
///
/// The @ref bslma_autodeallocator  component provides a range proctor class to
/// manage a sequence of blocks of (otherwise-unmanaged) memory of a parameterized
/// `TYPE` supplied at construction.  If not explicitly released, the sequence of
/// managed memory blocks are deallocated automatically when the range proctor
/// goes out of scope by freeing the memory using the parameterized `ALLOCATOR`
/// (allocator or pool) supplied at construction.  This proctor mechanism is
/// useful in guarding against memory leaks, e.g., when additional allocations may
/// throw an exception.
///
/// ### bslma_autodestructor {#bslma-bslma_autodestructor}
///
/// The @ref bslma_autodestructor  component provides a range proctor class to
/// manage a sequence of blocks of (otherwise-unmanaged) memory of a parameterized
/// `TYPE` supplied at construction.  If not explicitly released, the sequence of
/// managed memory blocks are destroyed automatically when the range proctor goes
/// out of scope by calling each (managed) object`s destructor.  This proctor
/// mechanism is useful in guarding against memory leaks, e.g., when additional
/// allocations may throw an exception.
///
/// ### bslma_autorawdeleter {#bslma-bslma_autorawdeleter}
///
/// The @ref bslma_autorawdeleter  component provides a range proctor class template
/// to manage a sequence of (otherwise-unmanaged) objects of parameterized `TYPE`
/// supplied at construction.  If not explicitly released, the sequence of managed
/// objects are deleted automatically when the range proctor goes out of scope by
/// iterating over each object, first calling the (managed) object`s destructor,
/// and then freeing its memory footprint by invoking the `deallocate` method of
/// an allocator (or pool) of parameterized `ALLOCATOR` type also supplied at
/// construction.  This proctor mechanism is useful in guarding against memory
/// leaks, e.g., when additional allocations may throw an exception.
///
/// ### bslma_deallocatorguard {#bslma-bslma_deallocatorguard}
///
/// The @ref bslma_deallocatorguard  component provides a guard class template to
/// *unconditionally* manage a block of (otherwise-unmanaged) memory.  The managed
/// memory is deallocated automatically when the guard object goes out of scope
/// using the `deallocate` method of the parameterized `ALLOCATOR` (allocator or
/// pool) supplied at construction.  This guard mechanism is useful in ensuring
/// that a dynamically allocated raw memory resource is safely deallocated in the
/// presense of multiple return satements or exceptions.
///
/// ### bslma_deallocatorproctor {#bslma-bslma_deallocatorproctor}
///
/// The @ref bslma_deallocatorproctor  component provides a proctor class template
/// to *conditionally* manage a block of (otherwise-unmanaged) memory.  If not
/// explicitly released, the managed memory is deallocated automatically when the
/// proctor object goes out of scope by freeing the memory using the parameterized
/// `ALLOCATOR` (allocator or pool) supplied at construction.  This proctor
/// mechanism is useful in guarding against memory leaks, e.g., when additional
/// allocations may throw an exception.
///
/// ### bslma_default {#bslma-bslma_default}
///
/// The @ref bslma_default  component provides a namespace for a set of utility
/// functions that manage the addresses of two static (global) memory allocator
/// instances: the *default* allocator and the *global* allocator.  The default
/// allocator is the allocator used by default by all BDE components.  The global
/// allocator is the allocator used by default to construct global singleton
/// objects.  Each of these allocators are of type derived from
/// `bslma::Allocator`.
///
/// ### bslma_defaultallocatorguard {#bslma-bslma_defaultallocatorguard}
///
/// The @ref bslma_defaultallocatorguard  component provides a mechanism that serves
/// as a "scoped guard" to enable the temporary replacement of the process-wide
/// default allocator.  This functionality is intended for *testing* only, and in
/// no event should this component be used except at the very beginning of `main`.
///
/// ### bslma_deleterhelper {#bslma-bslma_deleterhelper}
///
/// The @ref bslma_deleterhelper  component provides non-primitive procedures used
/// to delete objects of parameterized `TYPE` by first calling the destructor of
/// the object, and then freeing the memory footprint of the object using a
/// parameterized `ALLOCATOR` (allocator or pool) provided as a second argument.
///
/// ### bslma_destructorguard {#bslma-bslma_destructorguard}
///
/// The @ref bslma_destructorguard  component provides a guard class template to
/// *unconditionally* manage an (otherwise-unmanaged) object of parameterized
/// `TYPE` supplied at construction.  The managed object is destroyed
/// automatically when the guard object goes out of scope by calling the (managed)
/// object`s destructor.  This guard mechanism is useful in ensuring that a
/// dynamically allocated raw memory resource is safely deallocated in the
/// presense of multiple return satements or exceptions.
///
/// ### bslma_destructorproctor {#bslma-bslma_destructorproctor}
///
/// The @ref bslma_destructorproctor  component provides a proctor class template to
/// *conditionally* manage an (otherwise-unmanaged) object of parameterized `TYPE`
/// supplied at construction.  If not explicitly released, the managed object is
/// destroyed automatically when the proctor object goes out of scope by calling
/// the object`s destructor.  This proctor mechanism is useful in guarding against
/// memory leaks, e.g., when additional allocations may throw an exception.
///
/// ### bslma_isstdallocator {#bslma-bslma_isstdallocator}
///
///The @ref bslma_isstdallocator  component provides a meta-function,
///`bsl::IsStdAllocator`, that determines if a type meets the requirements for an
///allocator, as specified in [container.requirements.general].
///
/// ### bslma_mallocfreeallocator {#bslma-bslma_mallocfreeallocator}
///
/// The @ref bslma_mallocfreeallocator  component provides a wrapper around
/// `std::malloc` and `std::free` that adheres to the `bslma::Allocator` protocol
/// (i.e., provides `allocate` and `deallocate` functions).
///
/// ### bslma_newdeleteallocator {#bslma-bslma_newdeleteallocator}
///
/// The @ref bslma_newdeleteallocator  component provides a wrapper around
/// `operator new` and `operator delete` that adheres to the `bslma::Allocator`
/// protocol (i.e., provides an `allocate` function and a `deallocate` function).
///
/// ### bslma_rawdeleterguard {#bslma-bslma_rawdeleterguard}
///
/// The @ref bslma_rawdeleterguard  component provides a guard class template to
/// *unconditionally* manage an (otherwise-unmanaged) object of parameterized
/// `TYPE` supplied at construction.  The managed object is deleted automatically
/// when the guard object goes out of scope by first calling the (managed)
/// object`s destructor, and then freeing the memory using the parameterized
/// `ALLOCATOR` (allocator or pool) also supplied at construction.  This guard
/// mechanism is useful in ensuring that a dynamically allocated raw memory
/// resource is safely deallocated in the presense of multiple return satements or
/// exceptions.
///
/// ### bslma_rawdeleterproctor {#bslma-bslma_rawdeleterproctor}
///
/// The @ref bslma_rawdeleterproctor  component provides a proctor class template to
/// conditionally manage an (otherwise-unmanaged) object of parameterized `TYPE`
/// supplied at construction.  If not explicitly released, the managed object is
/// deleted automatically when the proctor object goes out of scope by first
/// calling the (managed) object`s destructor, and then freeing the memory using
/// the parameterized `ALLOCATOR` (allocator or pool) also supplied at
/// construction.  This proctor mechanism is useful in guarding against memory
/// leaks, e.g., when additional allocations may throw an exception.
///
/// ### bslma_testallocator {#bslma-bslma_testallocator}
///
/// The @ref bslma_testallocator  component provides an instrumented allocator that
/// implements the `bslma::Allocator` protocol and can be used to track various
/// aspects of memory allocated from it.  This allocator memory allocator uses
/// global functions `std::malloc` and `std::free` for allocations and
/// deallocations.
///
/// ### bslma_testallocatorexception {#bslma-bslma_testallocatorexception}
///
/// The @ref bslma_testallocatorexception  component defines an exception object for
/// use in testing exceptions during memory allocations.
///
/// ### bslma_testallocatormonitor {#bslma-bslma_testallocatormonitor}
///
/// The @ref bslma_testallocatormonitor  component provides a "monitor", a mechanism
/// class, that allows concise tests of state change (or lack of change) in the
/// test allocator provided at the monitor's construction.
///
/// ## Why Use Allocators {#bslma-why-use-allocators}
///
/// Allocators were originally introduced into STL to provide containers an
/// abstraction for the different pointer types on the Intel architecture (such as
/// near and far pointers).  After the C++ standard (section 20.1.5 of the 1998
/// standard) specified the requirements on an allocator type (`std::allocator`)
/// that use was rendered obsolete.  But the standard also specified that all
/// standard containers be parameterized on an allocator type that provides users
/// greater control over the memory usage of individual objects and allows an
/// application to control from where that memory comes (e.g., stack, heap, shared
/// memory) and how it is distributed.  By using allocators, an application can
/// ensure efficient memory usage by reducing the number of distinct calls to
/// global operators `new` and `delete` (and functions `std::malloc` and
/// `std::free`).
///
/// ## Rationale for the BDE Allocator Model {#bslma-rationale-for-the-bde-allocator-model}
///
/// Although C++ standard allocators (`std::allocator`) provide users great
/// control on how containers can allocate memory having a templated allocator
/// argument introduces other problems.  Two containers instantiated with
/// different allocator types refer to different types making interoperability
/// between them difficult and limiting the allocator type to a per-class (as
/// opposed to a per-instance) basis.  The standard's requirement of a templated
/// allocator type is limited to containers and does not address other
/// user-defined types that allocate memory.  Although users can augment their
/// types to take a templated allocator type such use is likely to be tedious and
/// to result in significant object code increase.  Finally, the standard is
/// unclear with regards to the copy semantics of stateful allocators.
///
/// The BDE allocator model provides a solution to these issues.  BDE provides an
/// allocator protocol and concrete allocator implementations that can be passed
/// as constructor arguments (not as template parameters) to all objects that
/// allocate memory.  The type of an object is unaffected by the passed-in
/// allocator and the user has full control over the scope of an allocator
/// instance.  As the model specifies a protocol it is easier to create concrete
/// implementations and use them.  The allocator model requires all elements (data
/// members) of a container (object) to use the same allocator as the container
/// (object).  Also the allocator is not transferred on copy construction.
///
/// ## Allocators and Other Memory-Dispensing Mechanisms {#bslma-allocators-and-other-memory-dispensing-mechanisms}
///
/// An allocator is a memory manager that derives from the `bslma::Allocator`
/// protocol and provides an `allocate` method for obtaining memory, and a
/// `deallocate` method for returning memory (to the allocator).  `bslma` also
/// provides many memory-dispensing mechanisms that also provide an `allocate` and
/// a `deallocate` method, but these memory managers are not properly referred to
/// as "allocators", since we reserve the term "allocator" for concrete memory
/// dispensers that actually derive from `bslma::Allocator` and are therefore
/// usable anywhere that a `bslma::Allocator *` is specified.  Objects that
/// dispense memory but that are not actually "allocators" are sometimes called
/// "end-point allocators", and may offer performance advantages to certain users.
/// Choosing an allocation mechanisms is complex, and many factors will influence
/// the decision.  The discussions here are aimed at shedding light on this
/// important selection process.
///
/// Characteristics differentiating among `bslma` memory-allocation objects *in*
/// *general* are:
///
/// * Whether or not the object isA `bslma::Allocator`.
///
/// * Whether or not the allocator supports memory reuse.
///
/// * Whether allocation requests consume the exact amount of memory requested,
///   an additive number of additional bytes, or a non-additive number of
///   additional bytes (e.g., the smallest power of two that can satisfy the
///   request).
///
/// * Whether allocation requests consume the exact amount of memory requested,
///
/// * Whether or not the allocator supports multi-threading.
///
/// All `bslma` allocators are fully thread-safe but not thread-enabled (see the
/// @ref bsldoc_glossary  for terminology).
///
/// The BDE allocators have two more differentiating properties.  First, whether
/// the allocator is intended to be part of a chain (or other grouping) of
/// allocators, or is an "end-point" allocator.  The former kind support the
/// `bslma::Allocator` protocol.  "End-point" allocators, such as a memory pool,
/// are general-purpose mechanisms designed to minimize the runtime overhead of
/// allocation and deallocation on a call-by-call basis and therefore do not
/// derive from `bslma::Allocator`.  The `bslma` package does not provide any
/// end-point allocators although such implementations may be provided in
/// higher-level libraries.
///
/// Supporting a common protocol (the `bslma::Allocator` protocol) allows passing
/// conformant allocators to BDE (and other) objects requiring an allocator at
/// construction.  Support of this common protocol also facilitates grouping the
/// memory used by an object into one allocator.
///
/// The BDE libraries use allocators with all classes requiring dynamic memory
/// allocation, allowing clients to fine-tune memory-related performance
/// characteristics by replacing the established defaults with client-chosen
/// alternatives.  Because the protocol is public, clients can even write their
/// own, customized implementations, and use those.  But none of these actions are
/// required.  BDE components all work with a (preset) default allocator, and
/// clients without special requirements need never concern themselves with
/// allocators.
///
/// ## Allocator and ManagedAllocator {#bslma-allocator-and-managedallocator}
///
/// A differentiating property among `bslma` allocators is whether the allocator
/// is a "managed" or "unmanaged" allocator.  Unmanaged allocators, concrete
/// implementations of `bslma::Allocator`, require every allocation to be matched
/// by a deallocation, similar to `malloc` and `free`, or `new` and `delete`.
/// Managed allocators, concrete implementations of `bslma::ManagedAllocator`, in
/// addition to implementing the `bslma::Allocator` protocol, provide simultaneous
/// deallocation of all memory with one call to `release`.  This `release`
/// optimization can provide significant performance improvements if the only
/// system resource held by an object (and all the objects it manages) is memory.
/// The `bslma` package does not provide any concrete managed allocator
/// implementations although such implementations may be provided in higher-level
/// libraries.
///
/// ## Proctors and Guards {#bslma-proctors-and-guards}
///
/// The `bslma` package contains many components for managing
/// dynamically-allocated objects.  These components can be divided along two
/// dimensions:
///
/// * What their objects do on destruction: The objects of these managers can
///   either deallocate, destroy, or delete (destroy and then deallocate) the
///   memory or object under management.
///
/// * Proctors or Guards: The object managers in this package can be divided
///   into guards and proctors.  See @ref bsldoc_glossary  for definitions of
///   "proctor" and "guard".  Proctors provide a mechanism to release the
///   managed object, whereas, at least within `bslma`, guards do not provide a
///   release mechanism (and so are slightly more efficient on destruction if a
///   release mechanism isn't needed).
///
/// The following table categorizes the various components along these dimensions:
///
/// @code
///                 Deallocation          Destruction          Deletion
///             +--------------------+-------------------+-------------------+
///  Proctor    | DeallocatorProctor | DestructorProctor | RawDeleterProctor |
///             +--------------------+-------------------+-------------------+
///  Guard      | DeallocatorGuard   | DestructorGuard   | RawDeleterGuard   |
///             +--------------------+-------------------+-------------------+
/// @endcode
///
/// Note that the components named "raw" (@ref bslma_rawdeleterproctor  and
/// @ref bslma_rawdeleterguard ) should be used only if we are sure that the supplied
/// pointer is !not! of a type that is a secondary base class -- i.e., the
/// (managed) object's address is (numerically) the same as when it was originally
/// dispensed by `ALLOCATOR`.
///
/// All of the object managers specified above manage an individual object or a
/// block of memory but three components, @ref bslma_autodeallocator ,
/// @ref bslma_autodestructor  and @ref bslma_autorawdeleter  allow users to manage a
/// sequence of objects or memory blocks.
///
/// ## Alignment {#bslma-alignment}
///
/// Alignment of an *address* in memory refers to the relative position of that
/// address with respect to specific (hardware-imposed) boundaries within the
/// memory space.  Any one address can be said to be on a one-byte boundary, a
/// two-byte boundary, a four-byte boundary, or an eight-byte boundary.  (Clearly,
/// this sequence can be extended, but, as of this writing, boundaries beyond
/// eight-byte boundaries are not relevant for these discussions on any hardware
/// platform of interest.  In particular, "alignment" as we are using the term
/// here does not deal with page boundaries or other larger memory structures,
/// although these considerations are important elsewhere.)
///
/// In general, we also speak about the alignment of (the *first* *byte* of) an
/// entity (e.g., an `int`, a `double`, or a pointer) whose size is not
/// necessarily one byte.  As a practical matter, for each entity separately, some
/// alignments are "safe" and some are not.  By "not safe" we mean that, for most
/// platforms (e.g., all of our Unix machines), attempting to access an entity at
/// an address that is not safely aligned for that entity will cause a bus error,
/// crashing the program on the spot.  In the very best case, the access will
/// incur a performance penalty as the memory is shifted appropriately between its
/// initial address and its target address (e.g., a register).
///
/// The BDE memory managers provide three kinds of alignment: NATURAL, MAXIMAL,
/// and BYTE -- but note that BYTE alignment is also referred to as "no alignment"
/// or "none" in this document, since every address is aligned to *some* byte.
///
/// A C/C++ variable is "naturally aligned" if its size divides the numerical
/// value of its address.  An address is "maximally aligned" if it can serve as a
/// naturally-aligned address no matter what type of object might be stored there.
/// That is, it meets the alignment requirements of the type with the maximally
/// restrictive needs.
///
/// Accessing data stored at an aligned address is *faster* on Intel platforms and
/// *required* on almost all Unix platforms.  Reading (or writing) a C/C++
/// variable at an unaligned address will cause a Bus Error on these Unix
/// platforms, and thus crash the program.
///
/// Normally, programmers need not worry about alignment for dynamically allocated
/// memory.  The runtime system's `new` (or `malloc`, for C) automatically return
/// memory blocks beginning at maximally-aligned addresses (the C++ standard
/// requires it of `new`).  All memory managers in the `bslma` package return
/// maximally-aligned memory.
///
/// The cost of obtaining aligned addresses is twofold: an increase in the memory
/// used (allocators returning aligned addresses do so by skipping bytes that
/// could otherwise be used, so as to return an appropriate address), and
/// additional computation time to calculate the needed alignment and subsequent
/// offset.
///
/// See the []{bsls_alignment#Alignment Strategy} component for further
/// information on the supported alignment strategies.
///
/// ## Deallocation {#bslma-deallocation}
///
/// Some managers may not deallocate individual items.  (The `deallocate` function
/// is almost always provided, but in these managers it performs no action.)  Such
/// managers provide a `release` function instead, which relinquishes *all* memory
/// allocated by that manager since the previous `release` call.  All memory
/// managers in the `bslma` package deallocate the specified memory during a
/// `deallocate` method invocation.
///
/// ## Type and Origination {#bslma-type-and-origination}
///
/// Most managers provide variable-sized, untyped (i.e., `void *`) memory.
///
/// Different components manage memory in different ways, but they necessarily
/// *obtain* the memory that they manage from one of the two usual sources: the
/// heap or the stack.  The `bslma::NewDeleteAllocator` is hard-coded to obtain
/// memory from the heap -- its underlying source is `operator new`.
///
/// The managers in the `bslma` package are compared in the following tables:
/// ```
///                                PERFORMANCE CHARACTERISTICS
///
///                 Memory Source     Allocation   Alignment     Out-of-memory
///                                   Cost OVER                     Handling
///                                   Underlying
///                                    Source
///              +-----------------+--------------+---------+--------------------+
///  NewDelete   | `operator new`  | 0 if inlined,|MAXIMAL  | Return value 0     |
///  Allocator   |                 |else vfn call+|         |                    |
///              +-----------------+--------------+---------+--------------------+
///  MallocFree  | `std::malloc`   | 0 if inlined,|MAXIMAL  | Return value 0     |
///  Allocator   |                 |else vfn call+|         |                    |
///              +-----------------+--------------+---------+--------------------+
///  Test        | `malloc`        |     N/A      |   None  | Return value 0     |
///  Allocator   |                 |              |         |                    |
///              +-----------------+--------------+---------+--------------------+
///
///                                       SEMANTICS
///
///                        Deallocation             Storage Facility
///                    +-----------------------+-------------------------+
///  Newdelete         | Single items only     | Untyped, varying sizes  |
///  Allocator         |                       |                         |
///                    +-----------------------+-------------------------+
///  MallocFree        | Single items only     | Untyped, varying sizes  |
///  Allocator         |                       |                         |
///                    +-----------------------+-------------------------+
///  Test              | Single items only     | Untyped, varying sizes  |
///  Allocator         |                       |                         |
///                    +-----------------------+-------------------------+
/// ```
///
/// ## The Default Allocator {#bslma-the-default-allocator}
///
/// All object types in BDE libraries needing dynamic memory require that an
/// allocator be passed to their constructor.  They take a `bslma::Allocator *`
/// argument, which defaults to the value of `bslma::Default::defaultAllocator()`.
/// This value is set by BDE library code to be
/// `bslma::NewDeleteAllocator::singleton()`, but it can be changed:
/// `bslma::Default::setDefaultAllocator` sets the value of the (global) default
/// allocator (although this is *strongly* discouraged), and
/// `bslma::Default::allocator` returns it.
///
/// ## Interaction With Other Packages {#bslma-interaction-with-other-packages}
///
/// All BDE library objects needing dynamic memory require that an allocator be
/// passed to their constructor, which defaults to the allocator currently
/// installed as the default allocator.
///
/// ## Usage {#bslma-usage}
///
/// This section illustrates intended use of components in this package.
///
/// ### Example 1: Creating a type that uses bslma::Allocator {#bslma-example-1-creating-a-type-that-uses-bslma-allocator}
///
/// If objects of a class allocate memory (or contain data members that do) then
/// having all constructors of that class accept the address of a
/// `bslma::Allocator` object as an argument allows its clients to control how
/// those objects allocate memory.  An example of this is provided by showing the
/// creators of a `Customer` `class` that stores the first and last names of a
/// customer as `bsl::string` objects and the various account numbers of that
/// customer using a `bsl::vector`.  For simplicity part of the interface is
/// elided.
/// ```
///                          // ==============
///                          // class Customer
///                          // ==============
///
///  /// This simply constrained (value-semantic) attribute class represents
///  /// the information about a bank's customer.  A customer's first and last
///  /// name are represented as `bsl::string` objects, the associated accounts
///  /// are stored in a `bsl::vector<int>`, and the employee identification
///  /// number is represented by an `int`.  Note that the class invariants are
///  /// identically the constraints on the individual attributes.
///  ///
///  /// This class:
///  /// * supports a complete set of *value-semantic* operations
///  ///   - except for `bslx` serialization
///  /// * is *exception-neutral* (agnostic)
///  /// * is *alias-safe*
///  /// * is `const` *thread-safe*
///  class Customer {
///
///      // DATA
///      bsl::string      d_firstName;       // first name
///      bsl::string      d_lastName;        // last name
///      bsl::vector<int> d_accounts;        // account numbers
///      int              d_id;              // customer identification number
///
///    public:
/// ```
/// Note that the constructor declarations below all accept the address of a
/// 'bslma::Allocator' argument.
/// ```
///      // CREATORS
///
///      /// Create a `Customer` object having the (default) attribute values:
///      /// ...
///      ///  firstName() == ""
///      ///  lastName()  == ""
///      ///  accounts()  == 0
///      ///  id()        == 0
///      /// ...
///      /// Optionally specify a `basicAllocator` used to supply memory.  If
///      /// `basicAllocator` is 0, the currently installed default allocator
///      /// is used.
///      Customer(bslma::Allocator *basicAllocator = 0);
///
///      /// Create a `Customer` object having the specified `firstName`,
///      /// `lastName`, `accounts`, and `id` attribute values.  Optionally
///      /// specify a `basicAllocator` used to supply memory.  If
///      /// `basicAllocator` is 0, the currently installed default allocator
///      /// is used.
///      Customer(const bslstl::StringRef&  firstName,
///               const bslstl::StringRef&  lastName,
///               const bsl::vector<int>&   accounts,
///               int                       id,
///               bslma::Allocator         *basicAllocator = 0);
///
///      /// Create a `Customer` object having the same value as the specified
///      /// `original` object.  Optionally specify a `basicAllocator` used to
///      /// supply memory.  If `basicAllocator` is 0, the currently installed
///      /// default allocator is used.
///      Customer(const Customer& original, bslma::Allocator *basicAllocator = 0);
///
///      /// Destroy this object.
///      //! ~Customer() = default;
///
///                                    // Aspects
///
///      /// Return the allocator used by this object to supply memory.  Note
///      /// that if no allocator was supplied at construction the currently
///      /// installed default allocator is used.
///      bslma::Allocator *allocator() const;
///
///      ...
///  };
/// ```
/// Since the `Customer` `class` contains members that allocate memory it can
/// associate the `UsesBslmaAllocator` trait defined in the `bslma` package to
/// programmatically inform templated code that it uses an allocator.
/// ```
///
///  // TRAITS
///  namespace BloombergLP{
///  namespace bslma {
///
///  template <> struct UsesBslmaAllocator<Customer> : bsl::true_type {};
///
///  }
///  }
///
///  // ==========================================================================
///  //                      INLINE FUNCTION DEFINITIONS
///  // ==========================================================================
///
///                          // --------------
///                          // class Customer
///                          // --------------
///
/// ```
/// The constructor implementations of 'Customer' can simply forward the
/// basicAllocator argument to its data members.  All BSL containers, including
/// 'bsl::string' and 'bsl::vector', accept a 'bslma::Allocator' constructor
/// argument:
/// ```
///
///  // CREATORS
///  inline
///  Customer::Customer(bslma::Allocator *basicAllocator)
///  : d_firstName(basicAllocator)
///  , d_lastName(basicAllocator)
///  , d_accounts(basicAllocator)
///  , d_id(0)
///  {
///  }
///
///  inline
///  Customer::Customer(const bslstl::StringRef&  firstName,
///                     const bslstl::StringRef&  lastName,
///                     const bsl::vector<int>&   accounts,
///                     int                       id,
///                     bslma::Allocator         *basicAllocator)
///  : d_firstName(firstName.begin(), firstName.end(), basicAllocator)
///  , d_lastName(lastName.begin(), lastName.end(), basicAllocator)
///  , d_accounts(accounts, basicAllocator)
///  , d_id(id)
///  {
///      BSLS_ASSERT_SAFE(!firstName.isEmpty());
///      BSLS_ASSERT_SAFE(!lastName.isEmpty());
///  }
///
///  inline
///  Customer::Customer(const Customer&   original,
///                     bslma::Allocator *basicAllocator)
///  : d_firstName(original.d_firstName, basicAllocator)
///  , d_lastName(original.d_lastName, basicAllocator)
///  , d_accounts(original.d_accounts, basicAllocator)
///  , d_id(original.d_id)
///  {
///  }
///
///  // MANIPULATORS
///  inline
///  Customer& Customer::operator=(const Customer& rhs)
///  {
///      d_firstName = rhs.d_firstName;
///      d_lastName  = rhs.d_lastName;
///      d_accounts  = rhs.d_accounts;
///      d_id        = rhs.d_id;
///      return *this;
///  }
///
///                                    // Aspects
///
///  inline
///  bslma::Allocator *Customer::allocator() const
///  {
///      return d_firstName.get_allocator().mechanism();
///  }
///
/// ```
/// Again for simplicity the rest of the implementation is not provided.
///
/// ### Example 2: Implementing Templates That May Be Supplied Allocating Types {#bslma-example-2-implementing-templates-that-may-be-supplied-allocating-types}
///
/// When writing templatized code that may be parameterized on types that allocate
/// memory it is often necessary to decide whether to pass through the
/// user-supplied allocator to individual objects.  Such code (and containers) can
/// use the UsesBslmaAllocator trait defined in the bslma package to decide
/// whether to pass the allocator to an object's constructor.  An example of using
/// this trait is provided below by showing a simplified parameterized object pool
/// `class`:
/// ```
///                          // ================
///                          // class ObjectPool
///                          // ================
///
///  /// This `class` provides a pool of reusable objects of the parameterized
///  /// `TYPE` and assumes that the parameterized `TYPE` provides a default
///  /// constructor, a destructor, and a `reset` method.
///  template <typename TYPE>
///  class ObjectPool {
///
///      // DATA
///      bsl::list<TYPE *>  d_objects;      // list of managed objects
///      bslma::Allocator  *d_allocator_p;  // memory allocator (held, not owned)
///
///      // PRIVATE CLASS METHODS
///
///      /// Construct an object of the specified `TYPE` that *does not*
///      /// require an allocator to be passed to its constructor.
///      TYPE *createObject(bsl::false_type);
///
///      /// Construct an object of the specified `TYPE` that *requires* an
///      /// allocator to be passed to its constructor.
///      TYPE *createObject(bsl::true_type);
///
///    public:
///      // CREATORS
///
///      /// Create an object pool that invokes the default constructor of the
///      /// parameterized `TYPE` to construct objects.  The optionally
///      /// specified `basicAllocator` is used to supply memory.  If
///      /// `basicAllocator` is 0, the currently installed default allocator
///      /// is used.
///      ObjectPool(bslma::Allocator *basicAllocator = 0);
///
///      /// Destroy this object pool.  All objects created by this pool are
///      /// destroyed (even if some of them are still in use) and memory is
///      /// reclaimed.
///      ~ObjectPool();
///
///      // MANIPULATORS
///
///      /// Return an address providing modifiable access to a
///      /// default-constructed object of the parameterized `TYPE`.  If this
///      /// pool does not have any free objects then a default-constructed
///      /// object is allocated and returned.
///      TYPE* getObject();
///
///      /// Return the specified `object` back to this object pool.  Invoke
///      /// the `reset` method on `object`.
///      void releaseObject(TYPE *object);
///
///      // The rest of the interface is elided for brevity.
///  };
///
///  // ==========================================================================
///  //                      INLINE FUNCTION DEFINITIONS
///  // ==========================================================================
///
///                          // ----------------
///                          // class ObjectPool
///                          // ----------------
///
/// ```
/// The 'createObject' private methods below allow an object to be created by
/// specifying an allocator only if it has the 'UsesBslmaAllocator' trait.
/// ```
///
///  // PRIVATE CLASS METHODS
///  template <typename TYPE>
///  inline
///  TYPE *ObjectPool<TYPE>::createObject(bsl::false_type)
///  {
///      return new (*d_allocator_p) TYPE();
///  }
///
///  template <typename TYPE>
///  inline
///  TYPE *ObjectPool<TYPE>::createObject(bsl::true_type)
///  {
///      return new (*d_allocator_p) TYPE(d_allocator_p);
///  }
///
///  // CREATORS
///  template <typename TYPE>
///  inline
///  ObjectPool<TYPE>::ObjectPool(bslma::Allocator *basicAllocator)
///  : d_objects(basicAllocator)
///  , d_allocator_p(bslma::Default::allocator(basicAllocator))
///  {
///  }
///
///  template <typename TYPE>
///  ObjectPool<TYPE>::~ObjectPool()
///  {
///      for (bsl::list<TYPE *>::iterator iter = d_objects.begin();
///           iter != d_objects.end();
///           ++iter) {
///          d_allocator_p->deleteObject(*iter);
///      }
///      d_objects.clear();
///  }
///
///  // MANIPULATORS
///  template <typename TYPE>
///  TYPE *ObjectPool<TYPE>::getObject()
///  {
///      if (d_objects.size()) {
///          TYPE *object = d_objects.back();
///          d_objects.pop_back();
///          return object;                                              // RETURN
///      }
///
///      return createObject(bslma::UsesBslmaAllocator<TYPE>());
///  }
///
///  template <typename TYPE>
///  inline
///  void ObjectPool<TYPE>::releaseObject(TYPE *object)
///  {
///      object->reset();
///      d_objects.push_back(object);
///  }
/// ```
///
/// ### Example 3: Implementing a Customized Allocator {#bslma-example-3-implementing-a-customized-allocator}
///
/// Since 'bslma::Allocator' is a protocol, users can create their own concrete
/// implementations for object-specific situations.  A complete example of a
/// concrete implementation that allocates memory from a user-supplied static
/// buffer and reverts to an allocator specified at construction if that buffer is
/// exhausted is provided below:
///
/// ```
///                          // =====================
///                          // class BufferAllocator
///                          // =====================
///
///  using namespace BloombergLP;
///
///  /// This `class` provides a concrete buffer allocator that implements the
///  /// `bslma::Allocator` interface, allocating memory blocks from a
///  /// fixed-size buffer that is supplied by the user at construction, or
///  /// from an optionally-specified allocator once that buffer is exhausted.
///  class BufferAllocator : public bslma::Allocator {
///
///      // DATA
///      char             *d_buffer_p;      // buffer to use for memory
///                                         // allocations (held, not owned)
///      int               d_bufferSize;    // initial buffer size
///      int               d_cursor;        // current cursor
///      bslma::Allocator *d_allocator_p;   // memory allocator to use once
///                                         // `d_buffer_p` is exhausted (held,
///                                         // not owned)
///
///    private:
///      // NOT IMPLEMENTED
///      BufferAllocator(const BufferAllocator&);
///      BufferAllocator& operator=(const BufferAllocator&);
///
///    public:
///      // CREATORS
///
///      /// Create a buffer allocator for allocating memory blocks from the
///      /// specified `buffer` of the specified `bufferSize`.  Optionally
///      /// specify a `basicAllocator` used to supply memory after that
///      /// `buffer` is exhausted.  If `basicAllocator` is 0, the currently
///      /// installed default allocator is used.
///      BufferAllocator(char             *buffer,
///                      int               bufferSize,
///                      bslma::Allocator *basicAllocator = 0);
///
///      /// Destroy this buffer allocator.
///      virtual ~BufferAllocator();
///
///      // MANIPULATORS
///
///      /// Return the address of a contiguous block of maximally-aligned
///      /// memory of the specified `size` (in bytes).  If `size` is 0 no
///      /// memory is allocated and 0 is returned.  If the allocation request
///      /// exceeds the remaining free memory space in the external buffer
///      /// supplied at construction, the allocator specified at construction
///      /// is used.  The behavior is undefined unless `0 <= size`.
///      virtual void *allocate(bsls::Types::size_type size);
///
///      /// Deallocate the specified `address` if it did not come from the
///      /// external buffer specified at construction and do nothing
///      /// otherwise.  Note that if the buffer specified at construction was
///      /// not exhausted then no deallocation overhead is incurred.
///      virtual void deallocate(void *address);
///  };
///
///  // ==========================================================================
///  //                      INLINE FUNCTION DEFINITIONS
///  // ==========================================================================
///
///                          // ---------------------
///                          // class BufferAllocator
///                          // ---------------------
///
///  // CREATORS
///  inline
///  BufferAllocator::BufferAllocator(char             *buffer,
///                                   int               bufferSize,
///                                   bslma::Allocator *basicAllocator)
///  : d_buffer_p(buffer)
///  , d_bufferSize(bufferSize)
///  , d_cursor(0)
///  , d_allocator_p(bslma::Default::allocator(basicAllocator))
///  {
///  }
///
///  inline
///  BufferAllocator::~BufferAllocator()
///  {
///  }
///
/// ```
/// The function definitions for the 'BufferAllocator' 'class' are provided below:
/// ```
///  // MANIPULATORS
///  void *BufferAllocator::allocate(bsls::Types::size_type size)
///  {
///      BSLS_ASSERT_SAFE(0 <= size);
///
///      // Calculate the appropriate aligned offset
///
///      const int offset = bsls::AlignmentUtil::calculateAlignmentOffset(
///                                      d_buffer_p + d_cursor,
///                                      bsls::AlignmentUtil::BSLS_MAX_ALIGNMENT);
///
///      if (d_cursor + offset + size > d_bufferSize) {
///          return d_allocator_p->allocate(size);                       // RETURN
///      }
///
///      void *result = static_cast<void *>(&d_buffer_p[d_cursor + offset]);
///      d_cursor += offset + size;
///
///      return result;
///  }
///
///  void BufferAllocator::deallocate(void *address)
///  {
///      if (!(d_buffer_p <= address && address < d_buffer_p + d_bufferSize)) {
///          d_allocator_p->deallocate(address);
///      }
///  }
/// ```
///
/// @}
/** @} */