bsls.h

Go to the documentation of this file.

/// @file bsls.h
///
///
/// @defgroup bsls Package bsls
/// @brief  Basic Standard Library System utilities (bsls)
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// [bsls]: group__bsls.html
/// @{
///
/// # Purpose {#bsls-purpose}
/// Provide system-level utilities for 'bsl'.
///
/// # Mnemonic {#bsls-mnemonic}
/// Basic Standard Library System utilities (bsls)
///
/// # Description {#bsls-description}
/// The 'bsls' package provides a variety of system utilities for use
/// by the 'bsl' library.  These utilities include:
///
///  * Various buffer types with different alignment properties.
///  * Uniform exception handling, even for non-exception build targets.
///  * A platform-dependent 64-bit integer type.
///  * Platform-identification routines.
///  * A timer component, and access to system time facilities.
///
/// Note that the above list is not meant to be exhaustive.  The sections below
/// provide more information about the individual components.
///
/// ## Hierarchical Synopsis
///
/// The 'bsls' package currently has 86 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. bsls_byteorder
///
///  15. bsls_alignedbuffer
///      bsls_alignment
///      bsls_byteorderutil
///      bsls_platformutil                                  !DEPRECATED!
///      bsls_systemtime
///
///  14. bsls_alignmentutil
///      bsls_bslexceptionutil
///      bsls_fuzztest
///      bsls_stopwatch
///      bsls_timeinterval
///
///  13. bsls_asserttest
///      bsls_byteorderutil_impl                                         !PRIVATE!
///      bsls_exceptionutil
///      bsls_fuzztestpreconditionexception
///      bsls_nameof
///      bsls_outputredirector
///      bsls_preconditions
///      bsls_spinlock
///      bsls_timeutil
///
///  12. bsls_assert
///
///  11. bsls_review
///
///  10. bsls_atomic
///      bsls_bslonce
///      bsls_log
///
///   9. bsls_atomicoperations
///
///   8. bsls_atomicoperations_sparc32_sun_cc                            !PRIVATE!
///      bsls_atomicoperations_sparc64_sun_cc                            !PRIVATE!
///      bsls_bsllock
///      bsls_objectbuffer
///      bsls_protocoltest
///
///   7. bsls_alignmentfromtype
///      bsls_assertimputil
///      bsls_asserttestexception
///      bsls_atomicoperations_sparc_sun_cc_default                      !PRIVATE!
///      bsls_bsllockimpl_win32                                          !PRIVATE!
///      bsls_cpp11                                         !DEPRECATED!
///      bsls_libraryfeatures
///      bsls_pointercastutil
///      bsls_util
///
///   6. bsls_alignmenttotype
///      bsls_annotation                                    !DEPRECATED!
///      bsls_atomicoperations_powerpc32_aix_xlc                         !PRIVATE!
///      bsls_atomicoperations_powerpc64_aix_xlc                         !PRIVATE!
///      bsls_consteval
///      bsls_keyword
///      bsls_nullptr
///      bsls_performancehint
///
///   5. bsls_atomicoperations_all_all_clangintrinsics                   !PRIVATE!
///      bsls_atomicoperations_all_all_gccintrinsics                     !PRIVATE!
///      bsls_atomicoperations_arm32_win_msvc                            !PRIVATE!
///      bsls_atomicoperations_arm64_win_msvc                            !PRIVATE!
///      bsls_atomicoperations_arm_all_gcc                               !PRIVATE!
///      bsls_atomicoperations_powerpc_aix_xlc_default                   !PRIVATE!
///      bsls_atomicoperations_powerpc_all_gcc                           !PRIVATE!
///      bsls_atomicoperations_x64_all_gcc                               !PRIVATE!
///      bsls_atomicoperations_x64_win_msvc                              !PRIVATE!
///      bsls_atomicoperations_x86_all_gcc                               !PRIVATE!
///      bsls_atomicoperations_x86_win_msvc                              !PRIVATE!
///      bsls_bsllockimpl_pthread                                        !PRIVATE!
///      bsls_compilerfeatures
///
///   4. bsls_assert_macroreset                                          !PRIVATE!
///      bsls_asserttest_macroreset                                      !PRIVATE!
///      bsls_atomicoperations_default                                   !PRIVATE!
///      bsls_buildtarget
///      bsls_int64                                         !DEPRECATED!
///      bsls_logseverity
///      bsls_review_macroreset                                          !PRIVATE!
///      bsls_stackaddressutil
///      bsls_systemclocktype
///      bsls_unspecifiedbool
///
///   3. bsls_alignmentimp
///      bsls_bslsourcenameparserutil
///      bsls_bsltestutil
///      bsls_linkcoercion
///      bsls_stackaddressutil_plinktimestamp                            !PRIVATE!
///      bsls_types
///
///   2. bsls_blockgrowth
///      bsls_bsldeprecationinformation
///      bsls_macroincrement
///      bsls_macrorepeat
///      bsls_nativestd                                     !DEPRECATED!
///      bsls_platform
///
///   1. bsls_deprecate                                     !DEPRECATED!
///      bsls_deprecatefeature
///      bsls_ident
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bsls_alignedbuffer :
///       Provide raw buffers with user-specified size and alignment.
/// 
///  @ref bsls_alignment :
///       Provide a namespace for enumerating memory alignment strategies.
/// 
///  @ref bsls_alignmentfromtype :
///       Provide a meta-function that maps a `TYPE` to its alignment.
/// 
///  @ref bsls_alignmentimp :
///       Provide implementation meta-functions for alignment computation.
/// 
///  @ref bsls_alignmenttotype :
///       Provide a meta-function mapping an `ALIGNMENT` to a primitive type.
/// 
///  @ref bsls_alignmentutil :
///       Provide constants, types, and operations related to alignment.
/// 
///  @ref bsls_annotation :                                     !DEPRECATED!
///       Provide support for compiler annotations for compile-time safety.
/// 
///  @ref bsls_assert :
///       Provide build-specific, runtime-configurable assertion macros.
/// 
///  'bsls_assert_macroreset':                                           !PRIVATE!
///       Undefine all macros from `bsls_assert.h` and `bsls_review.h`.
/// 
///  @ref bsls_assertimputil :
///       Provide utilities to implement @ref bsls_assert  and @ref bsls_review .
/// 
///  @ref bsls_asserttest :
///       Provide a test facility for assertion macros.
/// 
///  'bsls_asserttest_macroreset':                                       !PRIVATE!
///       Undefine macros related to `bsls_asserttest.h`.
/// 
///  @ref bsls_asserttestexception :
///       Provide an exception type to support testing for failed assertions.
/// 
///  @ref bsls_atomic :
///       Provide types with atomic operations.
/// 
///  @ref bsls_atomicoperations :
///       Provide platform-independent atomic operations.
/// 
///  'bsls_atomicoperations_all_all_clangintrinsics':                    !PRIVATE!
///       Implement atomic operations using clang `__c11_atomic_*` intrinsics
/// 
///  'bsls_atomicoperations_all_all_gccintrinsics':                      !PRIVATE!
///       Implement atomic operations using gcc `__atomic_*` intrinsics.
/// 
///  'bsls_atomicoperations_arm32_win_msvc':                             !PRIVATE!
///       Provide implementations of atomic operations for arm32/MSVC/Win.
/// 
///  'bsls_atomicoperations_arm64_win_msvc':                             !PRIVATE!
///       Provide implementations of atomic operations for arm64/MSVC/Win.
/// 
///  'bsls_atomicoperations_arm_all_gcc':                                !PRIVATE!
///       Provide implementations of atomic operations for ARM/GCC.
/// 
///  'bsls_atomicoperations_default':                                    !PRIVATE!
///       Provide default implementation for atomic operations.
/// 
///  'bsls_atomicoperations_powerpc32_aix_xlc':                          !PRIVATE!
///       Provide implementations of atomic operations for PowerPC/AIX-32bit.
/// 
///  'bsls_atomicoperations_powerpc64_aix_xlc':                          !PRIVATE!
///       Provide implementations of atomic operations for PowerPC/AIX-64bit.
/// 
///  'bsls_atomicoperations_powerpc_aix_xlc_default':                    !PRIVATE!
///       Provide default base implementations of atomics for PowerPC/AIX.
/// 
///  'bsls_atomicoperations_powerpc_all_gcc':                            !PRIVATE!
///       Provide implementations of atomic operations for gcc on PowerPC
/// 
///  'bsls_atomicoperations_sparc32_sun_cc':                             !PRIVATE!
///       Provide implementations of atomic operations for Sparc/Sun (32bit).
/// 
///  'bsls_atomicoperations_sparc64_sun_cc':                             !PRIVATE!
///       Provide implementations of atomic operations for Sparc/Sun (64bit).
/// 
///  'bsls_atomicoperations_sparc_sun_cc_default':                       !PRIVATE!
///       Provide default base implementations of atomics for Sparc/Sun.
/// 
///  'bsls_atomicoperations_x64_all_gcc':                                !PRIVATE!
///       Provide implementations of atomic operations for X86_64/GCC.
/// 
///  'bsls_atomicoperations_x64_win_msvc':                               !PRIVATE!
///       Provide implementations of atomic operations for X86_64/MSVC/Win64.
/// 
///  'bsls_atomicoperations_x86_all_gcc':                                !PRIVATE!
///       Provide implementations of atomic operations for X86/GCC.
/// 
///  'bsls_atomicoperations_x86_win_msvc':                               !PRIVATE!
///       Provide implementations of atomic operations for X86/MSVC/Windows.
/// 
///  @ref bsls_blockgrowth :
///       Provide a namespace for memory block growth strategies.
/// 
///  @ref bsls_bsldeprecationinformation :
///       Provide a macro to control `bsl` deprecations by release version.
/// 
///  @ref bsls_bslexceptionutil :
///       Provide functions for use in `bsl` that throw standard exceptions.
/// 
///  @ref bsls_bsllock :
///       Provide a platform-independent mutex for use below `bslmt`.
/// 
///  'bsls_bsllockimpl_pthread':                                         !PRIVATE!
///       Provide a mutex for use below `bslmt`.
/// 
///  'bsls_bsllockimpl_win32':                                           !PRIVATE!
///       Provide a mutex for use below `bslmt` for windows platform.
/// 
///  @ref bsls_bslonce :
///       Provide BSL a thread-safe way to execute code once per process.
/// 
///  @ref bsls_bslsourcenameparserutil :
///       Provide low-level functions for parsing source file names.
/// 
///  @ref bsls_bsltestutil :
///       Provide test utilities for `bsl` that do not use <iostream>.
/// 
///  @ref bsls_buildtarget :
///       Provide build-target information in object files.
/// 
///  @ref bsls_byteorder :
///       Provide byte-order manipulation macros.
/// 
///  @ref bsls_byteorderutil :
///       Provide byte-order swapping functions.
/// 
///  'bsls_byteorderutil_impl':                                          !PRIVATE!
///       Provide implementation of byte-order manipulation functions.
/// 
///  @ref bsls_compilerfeatures :
///       Provide macros to identify compiler support for C++11 features.
/// 
///  @ref bsls_consteval :
///       Provide macros related to compile-time evaluation.
/// 
///  @ref bsls_cpp11 :                                          !DEPRECATED!
///       Provide macros for C++11 forward compatibility.
/// 
///  @ref bsls_deprecate :                                      !DEPRECATED!
///       Provide machinery to deprecate interfaces on a per-version basis.
/// 
///  @ref bsls_deprecatefeature :
///       Provide machinery to deprecate entities in C++ code.
/// 
///  @ref bsls_exceptionutil :
///       Provide simplified exception constructs for non-exception builds.
/// 
///  @ref bsls_fuzztest :
///       Provide macros for use in fuzz testing narrow-contract functions.
/// 
///  @ref bsls_fuzztestpreconditionexception :
///       Provide an exception type for handling failed preconditions.
/// 
///  @ref bsls_ident :
///       Provide macros for inserting SCM Ids into source files.
/// 
///  @ref bsls_int64 :                                          !DEPRECATED!
///       Provide namespace for platform-dependent 64-bit integer types.
/// 
///  @ref bsls_keyword :
///       Provide macros for forward language dialect compatibility.
/// 
///  @ref bsls_libraryfeatures :
///       Provide macros to identify native standard library features.
/// 
///  @ref bsls_linkcoercion :
///       Provide a way to force a link-time dependency into an object.
/// 
///  'bsls_log':
///       Provide a namespace for low-level logging functions.
/// 
///  @ref bsls_logseverity :
///       Enumerate a set of logging severity levels.
/// 
///  @ref bsls_macroincrement :
///       Provide a macro to increment preprocessor numbers.
/// 
///  @ref bsls_macrorepeat :
///       repeat a macro invocation with different numeric arguments.
/// 
///  @ref bsls_nameof :
///       Provide a `NameOf` type for displaying template type at run-time.
/// 
///  @ref bsls_nativestd :                                      !DEPRECATED!
///       Define the namespace `native_std` as an alias for `::std`.
/// 
///  @ref bsls_nullptr :
///       Provide a distinct type for null pointer literals.
/// 
///  @ref bsls_objectbuffer :
///       Provide raw buffer with size and alignment of user-specified type.
/// 
///  @ref bsls_outputredirector :
///       Provide a means for test drivers to redirect and inspect output.
/// 
///  @ref bsls_performancehint :
///       Provide performance hints for code optimization.
/// 
///  @ref bsls_platform :
///       Provide compile-time support for platform/attribute identification.
/// 
///  @ref bsls_platformutil :                                   !DEPRECATED!
///       Provide consistent interface for platform-dependent functionality.
/// 
///  @ref bsls_pointercastutil :
///       Provide function to cast between function and data pointers.
/// 
///  @ref bsls_preconditions :
///       Provide macros for use in fuzz testing narrow contract functions.
/// 
///  @ref bsls_protocoltest :
///       Provide classes and macros for testing abstract protocols.
/// 
///  @ref bsls_review :
///       Provide assertion macros to safely identify contract violations.
/// 
///  'bsls_review_macroreset':                                           !PRIVATE!
///       Test driver utility to undefine all macros from `bsls_review.h`.
/// 
///  @ref bsls_spinlock :
///       Provide a spin lock.
/// 
///  @ref bsls_stackaddressutil :
///       Provide a utility for obtaining return addresses from the stack.
/// 
///  'bsls_stackaddressutil_plinktimestamp':                             !PRIVATE!
///       Declare and weakly define a `plink_timestamp___` global variable.
/// 
///  @ref bsls_stopwatch :
///       Provide access to user, system, and wall times of current process.
/// 
///  @ref bsls_systemclocktype :
///       Enumerate the set of system clock types.
/// 
///  @ref bsls_systemtime :
///       Provide utilities to retrieve the system time.
/// 
///  @ref bsls_timeinterval :
///       Provide a representation of a time interval.
/// 
///  @ref bsls_timeutil :
///       Provide a platform-neutral functional interface to system clocks.
/// 
///  @ref bsls_types :
///       Provide a consistent interface for platform-dependent types.
/// 
///  @ref bsls_unspecifiedbool :
///       Provide a class supporting the `unspecified bool` idiom.
/// 
///  @ref bsls_util :
///       Provide essential, low-level support for portable generic code.
///
/// ## Component Overview
///
/// This section provides a brief introduction to some of the components in the
/// 'bsls' package.  See the documentation in each component for full details.
///
/// ### @ref bsls_alignedbuffer 
///
/// The {@ref bsls_alignedbuffer } component provides a parameterized buffer type with
/// a user-specified compile-time size and user-specified alignment.  Typically,
/// such a type is used in situations where it is desirable to allocate a block of
/// properly-aligned raw memory from somewhere other than the heap, e.g., on the
/// stack or within an aggregate object, including within a union.  It is a
/// convenient way to create a small heap from which one or more objects are
/// allocated at run-time.
///
/// ### @ref bsls_alignment 
///
/// The {@ref bsls_alignment } component computes (at compile-time) platform-dependent
/// alignment information.  This component also provides a namespace for a suite
/// of compile-time constants and pure procedures that yield platform-dependent
/// alignment information for primitive and user-defined types, including the
/// maximum alignment for any type and the smallest fundamental type requiring
/// maximum alignment.  These functions, used in conjunction, are especially
/// useful for creating pools and allocators that rely on efficient alignment.
///
/// ### @ref bsls_alignmentfromtype 
///
/// The {@ref bsls_alignmentfromtype } component provides a meta-function that
/// provides the alignment for a 'TYPE' template parameter.
///
/// ### @ref bsls_alignmentimp 
///
/// The {@ref bsls_alignmentimp } component provides a suite of template
/// meta-functions that can be used to compute (at compile-time) various
/// platform-dependent alignment information.
///
/// ### @ref bsls_alignmenttotype 
///
/// The {@ref bsls_alignmenttotype } component provides a meta-function that defines a
/// primitive type with an alignment matching a 'ALIGNMENT' template parameter.
///
/// ### @ref bsls_alignmentutil 
///
/// The {@ref bsls_alignmentutil } component provides a suite of template
/// meta-functions that can be used to compute (at compile-time) various
/// platform-dependent alignment information.
///
/// ### @ref bsls_annotation 
///
/// The {@ref bsls_annotation } component provides a suite of preprocessor macros that
/// define compiler-specific compile-time annotations.
///
/// ### @ref bsls_assert 
///
/// The {@ref bsls_assert } component provides a set of "assert-like" macros to
/// implement a compile-time-selectable and run-time-configurable "defensive" or
/// "safe" mode.  It also provides a suite of "assert-failure handler" methods
/// suitable for runtime loading into the macros, via also provided methods.
/// Users may supply their own handler methods matching the proper signature.  To
/// allow the user more flexibility in changing handlers during program execution,
/// this component also provides a scoped guard that allows safe, temporary
/// changing of the failure handler in a limited scope.
///
/// ### @ref bsls_asserttest 
///
/// The {@ref bsls_asserttest } component provides a facility to test that
/// 'BSLS_ASSERT_*' macros are used as intended, in the appropriate build modes,
/// and have the expected effects.
///
/// ### @ref bsls_asserttestexception 
///
/// The {@ref bsls_asserttestexception } component implements an exception class,
/// 'bsls::AssertTestException', that provides a mechanism to convey context
/// information from a failing assertion to a test handler.
///
/// ### @ref bsls_atomic 
///
/// The {@ref bsls_atomic } component provides classes with atomic operations for
/// 'int', 'Int64', and pointer types.
///
/// ### @ref bsls_atomicoperations 
///
/// The {@ref bsls_atomicoperations } component provides a set of platform-independent
/// atomic operations for fundamental data types, such as 32-bit and 64-bit
/// integer and pointer.
///
/// ### @ref bsls_blockgrowth 
///
/// The {@ref bsls_blockgrowth } component enumerates the supported block growth
/// strategies.
///
/// ### @ref bsls_bsltestutil 
///
/// The {@ref bsls_bsltestutil } component provides the standard printing macros used
/// in BDE-style test drivers.
///
/// ### @ref bsls_buildtarget 
///
/// The {@ref bsls_buildtarget } component defines types and runtime constants for
/// identifying the build target information (usually specified to the compiler
/// via a set of 'BDE_BUILD_*' macros).  This is mostly useful for retrieving such
/// information from a linkable or executable binary.
///
/// ### @ref bsls_byteorder 
///
/// The {@ref bsls_byteorder } component provides a set host-to-network and
/// network-to-host byte-order manipulation macros.
///
/// ### @ref bsls_compilerfeatures 
///
/// The {@ref bsls_compilerfeatures } component provides a suite of preprocessor
/// macros to identify compiler-specific support of language features that may not
/// be available on all compilers in use across an organization.
///
/// ### @ref bsls_deprecate 
///
/// The {@ref bsls_deprecate } component provides a suite of macros to control (on a
/// per-version, per-UOR basis) the deprecation of functions, user-defined types,
/// and 'typedef's.
///
/// ### @ref bsls_exceptionutil 
///
/// The {@ref bsls_exceptionutil } component provides macros to replace 'try', 'throw'
/// and 'catch'.  These macros expand to normal exception constructs when
/// exceptions are enabled and to reasonable alternatives (usually no-ops) when
/// exceptions are disabled, allowing code that uses 'try', 'throw' and 'catch'
/// constructs to compile even if exceptions are disabled using a compiler switch.
///
/// ### @ref bsls_ident 
///
/// The {@ref bsls_ident } component provides macros for inserting SCM (Source Control
/// Management) Ids into source files.
///
/// ### @ref bsls_macroincrement 
///
/// The {@ref bsls_macroincrement } component provides a macro,
/// 'BSLS_MACROINCREMENT(NUMBER)', that produces the preprocessor number equal to
/// the number succeeding the supplied argument.
///
/// ### @ref bsls_nativestd 
///
/// The {@ref bsls_nativestd } component defines a namespace alias, 'native_std', that
/// serves as an alias for the 'std' namespace.
///
/// ### @ref bsls_nullptr 
///
/// The {@ref bsls_nullptr } component provides a limited emulation of the C++11 type,
/// 'std::nullptr_t', which can be used as a function parameter type to create an
/// overload set where null pointer literals are handled specially.
///
/// ### @ref bsls_objectbuffer 
///
/// The {@ref bsls_objectbuffer } component provides a parameterized buffer type,
/// 'bsls_ObjectBuffer', which is compile-time sized and aligned to hold a
/// specified object type.  Defining a 'bsls_ObjectBuffer<T>' object does not
/// cause the constructor for 'T' to be called.  Similarly, destroying the object
/// buffer does not call the destructor for 'T'.  Typically, a 'bsls_ObjectBuffer'
/// is used in situations where efficient (e.g., stack-based) storage is required
/// but where straightforward initialization or destruction of an object is not
/// possible.  It can also be used to create a 'union' containing non-POD element
/// types.
///
/// ### @ref bsls_performancehint 
///
/// The {@ref bsls_performancehint } component provides performance hints for the
/// compiler or hardware.
///
/// ### @ref bsls_platform 
///
/// The {@ref bsls_platform } component defines preprocessor macros that identify and
/// describe platform-specific attributes (at compile time).  These attributes
/// consist of the types and versions of operating system, processor(s), and
/// compiler that comprise the platform.
///
/// ### @ref bsls_protocoltest 
///
/// The {@ref bsls_protocoltest } component provides classes and macros for testing
/// abstract protocols.
///
/// ### @ref bsls_stopwatch 
///
/// The {@ref bsls_stopwatch } component implements a real-time (system clock)
/// interval timer.  A 'bsls_Stopwatch' object can accumulate and return only one
/// interval at a time, but may be started and stopped repeatedly without being
/// reset, so the elapsed time "interval" accumulated by a single object may be
/// from multiple, discontinuous segments of time.  The non-negative total
/// accumulated time (in seconds) is available as a 'double' value.
///
/// ### @ref bsls_systemclocktype 
///
/// The {@ref bsls_systemclocktype } component provides a namespace for the 'enum'
/// type 'bsls::SystemClockType::Enum', which enumerates the set of system clock
/// types.  A 'bsls::SystemClockType' is particularly important when providing
/// time-out values to synchronization methods where those time-outs must be
/// consistent in environments where the system clocks may be changed.
///
/// ### @ref bsls_timeutil 
///
/// The {@ref bsls_timeutil } component provides a set of platform-neutral pure
/// procedures to access real-time system clock functionality.  High-resolution
/// time functions intended for interval-timing return an interval in nanoseconds
/// (1 nsec = 1E-9 sec) as a 64-bit integer.
///
/// ### @ref bsls_types 
///
/// The {@ref bsls_types } component provides a namespace for a set of 'typedef's that
/// provide a stable, portable interface to platform-dependent types.
///
/// ### @ref bsls_unspecifiedbool 
///
/// The {@ref bsls_unspecifiedbool } component provides a class template that can be
/// used to manufacture an "unspecified boolean type" that is distinct for each
/// class that instantiates it.  *Not* for use outside the 'bsl' package.
///
/// ### @ref bsls_util 
///
/// The {@ref bsls_util } component provides pure functions that supply essential
/// low-level support for implementing portable generic facilities such as might
/// be found in the C++ standard library.
///
/// ## Movable and Forwarding Reference Macros And Utilities
///
/// Modern C++ (C++11 and later) introduces the concepts of moving and forwarding
/// function arguments.  The BDE library provides facilities to replicate these
/// features in C++03, and also allow writing code in a way that the same code can
/// be compiled in both C++03 and in modern C++ (where the features are natively
/// supported).  This document describes which of these BDE facilities to use in
/// which contexts.  This section assumes familiarity with movable types and the
/// use of {@ref bslmf_movableref } for move semantics in C++03-compatible code.
///
/// ### Summary
///
/// Four utilities are to be described and their correct usage explained, and
/// they are summarized in the following table.  The term "forwarding" refers to
/// passing a variable recieved as an argument in one function to another
/// function, generally without altering it.  The term "perfect forwarding"
/// refers to forwarding not only the value that the argument represents, but
/// also characterstics of the argument such as cv-qualifications, and whether it
/// is an rvalue or an lvalue.
///
///  'BSLS_COMPILERFEATURES_FORWARD_REF(T)':
///      Used to declare a function template argument of type 'T' that is to be
///      perfect-forwarded.
///  'BSLS_COMPILERFEATURES_FORWARD(T, V)':
///      Used to perfect-forward a function template argument, 'V', of type 'T'.
///  'BSLMF_MOVABLEREF_DEDUCE(T)':
///      Used to deduce the type 'T' of a templated rvalue reference argument.
///  'bslmf::ForwardingType' and 'bslmf::ForwardingRefType':
///      Used to forward arguments through layers of nested calls efficiently.
///
/// The following sections explain in detail the contexts in which the above
/// macros and types are used.
///
/// ### Perfect Forwarding
///
/// In modern C++, function parameters marked with double ampersands ('&&') can
/// either be movable references or forwarding references.  The difference is
/// whether the type of the parameter excluding the '&&' is a template type of the
/// function (templates are forwarding references, non-templates are movable
/// references).  Forwarding references are lvalues that can bind to either an
/// lvalue reference or an rvalue reference, and can be converted back to the
/// original reference type with 'bsl::forward'.  The BDE library achieves this
/// effect in C++03 with two macros, 'BSLS_COMPILERFEATURES_FORWARD_REF' and
/// 'BSLS_COMPILERFEATURES_FORWARD'.
///
/// 'BSLS_COMPILERFEATURES_FORWARD_REF(T)' is used to declare a function template
/// argument of type 'T' that is to be perfect-forwarded.
///
/// 'BSLS_COMPILERFEATURES_FORWARD(T, V)' is used to perfect-forward a function
/// template argument, 'V', of type 'T'.
///
/// For example:
/// @code
///  template <class T>
///  void deduce(BSLS_COMPILERFEATURES_FORWARD_REF(T) t) // Forwarding reference
///  {
///      Forwarded tt(BSLS_COMPILERFEATURES_FORWARD(T, t)); // Perfect forwarding
///  }
/// @endcode
///
/// ### Short Complete Example
///
/// The following code will compile and run in any BDE-supported version of C++.
/// @code
///  #include <bslmf_movableref.h>
///  #include <bslmf_util.h>
///  
///  #include <bsls_compilerfeatures.h>
///  
///  #include <bsl_iostream.h>
///  #include <bsl_utility.h>
///  
///  using namespace BloombergLP;
///  
///  struct Forwarded;
///  
///  // =====================================================================
///  // Parameter 't' of function 'deduce' is a forwarding reference that is
///  // forwarded to the constructor of local 'tt' to demonstrate being moved
///  // or copied, depending on the type of the parameter passed.
///  // =====================================================================
///  template <class T>
///  void deduce(BSLS_COMPILERFEATURES_FORWARD_REF(T) t)  // Forwarding reference
///  {
///      Forwarded tt(BSLS_COMPILERFEATURES_FORWARD(T, t));  // Perfect forwarding
///  }
///  
///  struct Forwarded
///  {
///      // A class to demonstrate whether moving or copying is taking place
///      Forwarded(){bsl::cout << "Default\n";}
///      Forwarded(const Forwarded&){bsl::cout << "Copy\n";}
///      Forwarded(bslmf::MovableRef<Forwarded>){bsl::cout << "Move\n";}
///  };
///  
///  int main()
///  {
///      Forwarded f;
///      deduce(f);                               // Parameter is lvalue reference
///      deduce(bslmf::MovableRefUtil::move(f));  // Parameter is rvalue reference
///  }
/// @endcode
/// This program should output the following.
/// @code
///  Default
///  Copy
///  Move
/// @endcode
///
/// ### Movable Reference to Templated Type
///
/// 'bslmf::MovableRef' is a template facility that provides move semantics in
/// C++03.  One common issue with 'MovableRef<T>' is its use in a context where
/// 'T' itself is a template parameter: the compiler will be unable to deduce the
/// type of 'T' in C++11 (or later) as one would expect.  For example:
/// @code
///  template <class T>
///  void f(bslmf::MovableRef<A<T> > a);
///
///  int main()
///  {
///      A<int> a1;
///      f(bslmf::MovableRefUtil::move(a1)); // COMPILE ERROR! Can't deduce 'T'.
///  }
/// @endcode
/// To deduce this type, the macro 'BSLMF_MOVABLEREF_DEDUCE' can be used, for
/// example:
/// @code
///  template <class T>
///  void g(BSLMF_MOVABLEREF_DEDUCE(A<T>) a);
///      // A function that takes a 'MovableRef<A<T>>'
///
///  int main()
///  {
///      A<int> a2;
///      g(bslmf::MovableRefUtil::move(a2)); // compiles!
///  }
/// @endcode
/// A real world example can be found in component {@ref bdlb_nullablevalue }.  The
/// 'bdlb::NullableValue<TYPE>' constructor taking a movable reference to a
/// 'bdlb::NullableValue<BDE_OTHER_TYPE>', with 'BDE_OTHER_TYPE' convertible to
/// 'TYPE', uses 'BSLMF_MOVABLEREF_DEDUCE'.
/// @code
///  template <class BDE_OTHER_TYPE>
///  NullableValue(BSLMF_MOVABLEREF_DEDUCE(
///                                    NullableValue<BDE_OTHER_TYPE>) value,
///                const allocator_type&                              allocator,
///                typename bsl::enable_if<
///                   bsl::is_convertible<BDE_OTHER_TYPE, TYPE>::value &&
///                   !bsl::is_same<bsl::optional<BDE_OTHER_TYPE>, TYPE>::value,
///                   EnableType>::type = EnableType());             // IMPLICIT
/// @endcode
///
/// ### Forwarding Parameters Through Many Layers Efficiently
///
/// Generic code that forwards arguments through many layers of metaprogramming
/// templates -- e.g., 'bsl::function' and 'bsl::bind' -- can be made more
/// efficient through judicious use of 'bslmf::ForwardingRefType'.  This allows a
/// number of small optimizations. For example, the collapse of array references
/// to pointers that are unpacked only once, thereby reducing the number of
/// template instantiations of the middle layers.  The older
/// 'bslmf::ForwardingType' served the same purpose, but is no longer recommended
/// since 'bslmf::ForwardingRefType' is simpler to use.
///
/// *Note:* *The* *component* @ref bslmf_forwardingreftype  *is* *a* *complex* *tool*
/// *with* *a* *singular* *purpose,* *and* *occassions* *for* *its* *legitimate*
/// *use* *are* *rare*.
///
///
/// @}
/** @} */