ball_log.h

Go to the documentation of this file.

/// @file ball_log.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// ball_log.h                                                         -*-C++-*-
#ifndef INCLUDED_BALL_LOG
#define INCLUDED_BALL_LOG
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup ball_log ball_log
/// @brief  Provide macros and utility functions to facilitate logging.
/// @addtogroup bal
/// @{
/// @addtogroup ball
/// @{
/// @addtogroup ball_log
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#ball_log-purpose"> Purpose</a>
/// * <a href="#ball_log-classes"> Classes </a>
/// * <a href="#ball_log-macros"> Macros </a>
/// * <a href="#ball_log-description"> Description </a>
///   * <a href="#ball_log-hierarchical-vs-non-hierarchical-category-creation"> Hierarchical vs. Non-Hierarchical Category Creation </a>
///   * <a href="#ball_log-thread-safety"> Thread Safety </a>
///   * <a href="#ball_log-macro-reference"> Macro Reference </a>
///     * <a href="#ball_log-macros-for-defining-categories-at-block-scope"> Macros for Defining Categories at Block Scope </a>
///     * <a href="#ball_log-macro-for-defining-categories-at-class-scope"> Macro for Defining Categories at Class Scope </a>
///     * <a href="#ball_log-macro-for-defining-categories-at-namespace-or-global-scope"> Macro for Defining Categories at Namespace or Global Scope </a>
///     * <a href="#ball_log-deprecated-macros-for-hierarchical-categories"> Deprecated Macros for Hierarchical Categories </a>
///     * <a href="#ball_log-macros-for-defining-legacy-non-hierarchical-categories"> Macros for Defining Legacy Non-Hierarchical Categories </a>
///     * <a href="#ball_log-macros-for-logging-records"> Macros for Logging Records </a>
///     * <a href="#ball_log-macros-for-logging-code-blocks"> Macros for Logging Code Blocks </a>
///     * <a href="#ball_log-utility-macros"> Utility Macros </a>
///   * <a href="#ball_log-usage"> Usage </a>
///     * <a href="#ball_log-example-1-a-basic-logging-example"> Example 1: A Basic Logging Example </a>
///     * <a href="#ball_log-example-2-setting-the-current-log-category"> Example 2: Setting the Current Log Category </a>
///     * <a href="#ball_log-example-3-c-io-streams-style-logging-macros"> Example 3: C++ IO Streams-Style Logging Macros </a>
///     * <a href="#ball_log-example-4-printf-style-output"> Example 4: printf-Style Output </a>
///     * <a href="#ball_log-example-5-dynamic-categories"> Example 5: Dynamic Categories </a>
///     * <a href="#ball_log-example-6-rule-based-logging"> Example 6: Rule-Based Logging </a>
///     * <a href="#ball_log-example-7-logging-using-a-callback"> Example 7: Logging Using a Callback </a>
///     * <a href="#ball_log-example-8-class-scope-logging"> Example 8: Class-Scope Logging </a>
///
/// # Purpose {#ball_log-purpose}
/// Provide macros and utility functions to facilitate logging.
///
/// # Classes {#ball_log-classes}
///
/// -  ball::Log: namespace for logging utilities (for *internal* use only)
///
/// # Macros {#ball_log-macros}
///
/// -  BALL_LOG_SET_CATEGORY(C): set category hierarchically to the specified C
/// -  BALL_LOG_SET_DYNAMIC_CATEGORY(C): set run-time category hierarchically
/// -  BALL_LOG_SET_CLASS_CATEGORY(C): set class category hierarchically
/// -  BALL_LOG_SET_NAMESPACE_CATEGORY(C): set namespace category hierarchically
/// -  BALL_LOG_SET_LEGACY_CATEGORY(C): set category non-hierarchically (legacy)
/// -  BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY(C): set run-time category (legacy)
/// -  BALL_LOG_SET_LEGACY_CLASS_CATEGORY(C): set class category (legacy)
/// -  BALL_LOG_SET_LEGACY_NAMESPACE_CATEGORY(C): set namespace category (legacy)
/// -  BALL_LOG_SET_CATEGORY_HIERARCHICALLY(C): !DEPRECATED! use
/// -                                            BALL_LOG_SET_CATEGORY
/// -  BALL_LOG_SET_DYNAMIC_CATEGORY_HIERARCHICALLY(C): !DEPRECATED! use
/// -                                            BALL_LOG_SET_DYNAMIC_CATEGORY
/// -  BALL_LOG_SET_CLASS_CATEGORY_HIERARCHICALLY(C): !DEPRECATED! use
/// -                                            BALL_LOG_SET_CLASS_CATEGORY
/// -  BALL_LOG_SET_NAMESPACE_CATEGORY_HIERARCHICALLY(C): !DEPRECATED! use
/// -                                            BALL_LOG_SET_NAMESPACE_CATEGORY
/// -  BALL_LOG_TRACE: produce a log record with the `e_TRACE` severity level
/// -  BALL_LOG_DEBUG: produce a log record with the `e_DEBUG` severity level
/// -  BALL_LOG_INFO: produce a log record with the `e_INFO` severity level
/// -  BALL_LOG_WARN: produce a log record with the `e_WARN` severity level
/// -  BALL_LOG_ERROR: produce a log record with the `e_ERROR` severity level
/// -  BALL_LOG_FATAL: produce a log record with the `e_FATAL` severity level
/// -  BALL_LOG_STREAM(SEV): produce a log record with the specified `SEV` level
/// -  BALL_LOGCB_TRACE(CB): produce a `e_TRACE` log record using callback `CB`
/// -  BALL_LOGCB_DEBUG(CB): produce a `e_DEBUG` log record using callback `CB`
/// -  BALL_LOGCB_INFO(CB): produce an `e_INFO` log record using callback `CB`
/// -  BALL_LOGCB_WARN(CB): produce a `e_WARN` log record using callback `CB`
/// -  BALL_LOGCB_ERROR(CB): produce an `e_ERROR` log record using callback `CB`
/// -  BALL_LOGCB_FATAL(CB): produce a `e_FATAL` log record using callback `CB`
/// -  BALL_LOGCB_STREAM(SEV, CB): produce a `SEV` log record using callback
/// -  BALL_LOGVA_TRACE(MSG, ...): produce `e_TRACE` record using `printf` format
/// -  BALL_LOGVA_DEBUG(MSG, ...): produce `e_DEBUG` record using `printf` format
/// -  BALL_LOGVA_INFO( MSG, ...): produce `e_INFO` record using `printf` format
/// -  BALL_LOGVA_WARN( MSG, ...): produce `e_WARN` record using `printf` format
/// -  BALL_LOGVA_ERROR(MSG, ...): produce `e_ERROR` record using `printf` format
/// -  BALL_LOGVA_FATAL(MSG, ...): produce `e_FATAL` record using `printf` format
/// -  BALL_LOGVA(SEV, MSG, ...): produce a `SEV` log record using `printf` format
/// -  BALL_LOG_TRACE_BLOCK: set code block with `e_TRACE` condition of execution
/// -  BALL_LOG_DEBUG_BLOCK: set code block with `e_DEBUG` condition of execution
/// -  BALL_LOG_INFO_BLOCK: set a code block with `e_INFO` condition of execution
/// -  BALL_LOG_WARN_BLOCK: set a code block with `e_WARN` condition of execution
/// -  BALL_LOG_ERROR_BLOCK: set code block with `e_ERROR` condition of execution
/// -  BALL_LOG_FATAL_BLOCK: set code block with `e_FATAL` condition of execution
/// -  BALL_LOG_STREAM_BLOCK(SEV): set a code block with `SEV` condition
/// -  BALL_LOGCB_TRACE_BLOCK(CB): set `e_TRACE` block with the specified callback
/// -  BALL_LOGCB_DEBUG_BLOCK(CB): set `e_DEBUG` block with the specified callback
/// -  BALL_LOGCB_INFO_BLOCK(CB): set `e_INFO` block with the specified callback
/// -  BALL_LOGCB_WARN_BLOCK(CB): set `e_WARN` block with the specified callback
/// -  BALL_LOGCB_ERROR_BLOCK(CB): set an `e_ERROR` block with the specified `CB`
/// -  BALL_LOGCB_FATAL_BLOCK(CB): set `e_FATAL` block with the specified callback
/// -  BALL_LOGCB_STREAM_BLOCK(SEV, CB): set a `SEV` block with the specified `CB`
/// -  BALL_LOG_IS_ENABLED(SEV): indicate if `SEV` is severe enough for logging
///
/// @see  ball_loggermanager, ball_category, ball_severity, ball_record
///
/// # Description {#ball_log-description}
/// This component provides preprocessor macros and utility
/// functions to facilitate use of the @ref ball_loggermanager  component.  In
/// particular, the macros defined herein greatly simplify the mechanics of
/// generating log records.  The utility functions provided in `ball::Log` are
/// intended only for use by the macros and should *not* be called directly.
///
/// The macros defined herein pertain to the logger manager singleton only, and
/// not to any non-singleton instances of `ball::LoggerManager`.  In particular,
/// the macros do not have any effect unless the logger manager singleton is
/// initialized.  Note that the flow of control may pass through a use of any of
/// the macros *before* the logger manager singleton has been initialized or
/// *after* it has been destroyed; however, control should not pass through any
/// macro use *during* logger manager singleton initialization or destruction.
/// See {@ref ball_loggermanager |Logger Manager Singleton Initialization} for
/// details on the recommended procedure for initializing the singleton.
///
/// ## Hierarchical vs. Non-Hierarchical Category Creation {#ball_log-hierarchical-vs-non-hierarchical-category-creation}
///
///
/// By default, all category-setting macros in this component use *hierarchical*
/// category creation.  When a category is created hierarchically, its threshold
/// levels are inherited from the existing non-default category whose name is
/// the longest matching prefix of the new category's name.  For example, if a
/// category "X.Y" exists with custom threshold levels, creating a new category
/// "X.Y.Z" hierarchically will cause "X.Y.Z" to inherit the threshold levels
/// from "X.Y" rather than using the category manager's default threshold
/// levels (static or callback-provided).  This hierarchical inheritance
/// provides a natural way to configure logging thresholds for related
/// subsystems.
///
/// Threshold levels can also be inherited from *orphaned* *settings*.  An
/// orphaned setting is a set of threshold levels that has been configured for a
/// category name that does not yet exist (via
/// `ball::CategoryManager::setThresholdLevelsHierarchically`).  When a category
/// is later created with that name (or a name that has the orphaned setting's
/// name as a prefix), it inherits from the orphaned setting.  This allows
/// pre-configuring thresholds for categories before any code that uses those
/// categories has executed.  Orphaned settings take precedence over existing
/// parent categories when both match.
///
/// In contrast, *non-hierarchical* (or *legacy*) category creation always uses
/// the category manager's default threshold levels (static or
/// callback-provided) for new categories, regardless of whether parent
/// categories exist.  This was the original behavior of the standard category
/// macros before hierarchical category creation was successfully sped up.
///
/// The standard macros (`BALL_LOG_SET_CATEGORY`,
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`, `BALL_LOG_SET_CLASS_CATEGORY`, and
/// `BALL_LOG_SET_NAMESPACE_CATEGORY`) create categories hierarchically by
/// default.  For backward compatibility, legacy non-hierarchical versions of
/// these macros are provided with the `_LEGACY_` prefix (e.g.,
/// `BALL_LOG_SET_LEGACY_CATEGORY`).  The legacy macros should only be used in
/// existing code that depends on non-hierarchical behavior; new code should
/// use the standard hierarchical macros.
///
/// Note that the `_HIERARCHICALLY` suffixed macros
/// (`BALL_LOG_SET_CATEGORY_HIERARCHICALLY`, etc.) are deprecated and redundant,
/// as the standard macros provide the same hierarchical behavior.
///
/// ## Thread Safety {#ball_log-thread-safety}
///
///
/// All macros defined in this component are thread-safe, and can be invoked
/// concurrently by multiple threads.
///
/// Additionally, each use of a logging macro will create a distinct log record,
/// and `ball::Observer` implementations (like those in `ball`) generally
/// guarantee that output for different log records are not interleaved.
///
/// ## Macro Reference {#ball_log-macro-reference}
///
///
/// This section documents the preprocessor macros defined in this component.
///
/// The first three macros described below are used to define categories, at
/// either block scope or class scope, to which records are logged by the C++
/// stream-based and `printf`-style logging macros (described further below).
///
/// ### Macros for Defining Categories at Block Scope {#ball_log-macros-for-defining-categories-at-block-scope}
///
///
/// The following macros are used to establish logging categories that have
/// block scope:
///
/// * `BALL_LOG_SET_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) using hierarchical category
///      creation.  On the *first* invocation of this macro in a code block,
///      the `ball::Log::setCategoryHierarchically` method is invoked to
///      retrieve the address of an appropriate category structure for its
///      scope; subsequent invocations will use a cached address of the
///      category.  (See the function-level documentation of
///      `ball::Log::setCategoryHierarchically` for more information.)  This
///      macro must be used at block scope, and can be used at most once in any
///      given block (or else a compiler diagnostic will result).  Note that
///     this macro uses hierarchical category creation; use
///     `BALL_LOG_SET_LEGACY_CATEGORY` for the legacy non-hierarchical
///     behavior.
///
/// * `BALL_LOG_SET_DYNAMIC_CATEGORY(CATEGORY)`:
///      Set, *on* *EACH* *invocation*, a category for logging to the specified
///      `CATEGORY` (assumed to be of type convertible to `const char *`) using
///      hierarchical category creation.  On *EVERY* invocation of this macro
///      in a code block, the `ball::Log::setCategoryHierarchically` method is
///      invoked to retrieve the address of an appropriate category structure
///      for its scope; the address returned from
///      `ball::Log::setCategoryHierarchically` is *NOT* cached for subsequent
///      calls.  (See the function-level documentation of
///      `ball::Log::setCategoryHierarchically` for more information.)  This
///      macro must be used at block scope and can be used at most once in any
///      given block (or else a compiler diagnostic will result).  Note that
///      this macro should be used to create categories that depend on
///      *RUN-TIME* values only (e.g., LUW or UUID).  Also note that this macro
///      uses hierarchical category creation; use
///      `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY` for the legacy non-hierarchical
///      behavior.
///
/// * `BALL_LOG_SET_LEGACY_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) using non-hierarchical category
///      creation.  On the *first* invocation of this macro in a code block,
///      the `ball::Log::setCategory` method is invoked to retrieve the address
///      of an appropriate category structure for its scope; subsequent
///      invocations will use a cached address of the category.  (See the
///      function-level documentation of `ball::Log::setCategory` for more
///      information.)  This macro must be used at block scope, and can be used
///      at most once in any given block (or else a compiler diagnostic will
///      result).  Note that this macro provides the legacy non-hierarchical
///      behavior; new code should prefer `BALL_LOG_SET_CATEGORY`.
///
/// * `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY(CATEGORY)`:
///      Set, *on* *EACH* *invocation*, a category for logging to the specified
///      `CATEGORY` (assumed to be of type convertible to `const char *`) using
///      non-hierarchical category creation.  On *EVERY* invocation of this
///      macro in a code block, the `ball::Log::setCategory` method is invoked
///      to retrieve the address of an appropriate category structure for its
///      scope; the address returned from `ball::Log::setCategory` is *NOT*
///      cached for subsequent calls.  (See the function-level documentation of
///      `ball::Log::setCategory` for more information.)  This macro must be
///      used at block scope and can be used at most once in any given block
///      (or else a compiler diagnostic will result).  Note that this macro
///      should be used to create categories that depend on *RUN-TIME* values
///      only (e.g., LUW or UUID).  Also note that this macro provides the
///      legacy non-hierarchical behavior; new code should prefer
///      `BALL_LOG_SET_DYNAMIC_CATEGORY`.
///
/// There can be at most one use of `BALL_LOG_SET_CATEGORY`,
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`, `BALL_LOG_SET_LEGACY_CATEGORY`, or
/// `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY` in any given block (or else a
/// compiler diagnostic will result).  Note that categories that are set using
/// these macros, including dynamic categories, are not destroyed until the
/// logger manager singleton is destroyed.
///
/// ### Macro for Defining Categories at Class Scope {#ball_log-macro-for-defining-categories-at-class-scope}
///
///
/// The following macros are used to establish logging categories that have
/// class scope:
///
/// * `BALL_LOG_SET_CLASS_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the scope of the class within
///      which this macro is used, using hierarchical category creation.
///      Similar to `BALL_LOG_SET_CATEGORY`, the category is set *once* only,
///      the first time that it is accessed (i.e., it is not a dynamic
///      category).  This macro must be used, at most once, within the
///      definition of a class or class template (or else a compiler diagnostic
///      will result).  Note that use of this macro may occur in either a
///      `public`, `private`, or `protected` section of a class's interface,
///      although `private` should be preferred.  Also note that this macro uses
///      hierarchical category creation; use
///      `BALL_LOG_SET_LEGACY_CLASS_CATEGORY` for the legacy non-hierarchical
///      behavior.
///
/// * `BALL_LOG_SET_LEGACY_CLASS_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the scope of the class within
///      which this macro is used, using non-hierarchical category creation.
///      Similar to `BALL_LOG_SET_LEGACY_CATEGORY`, the category is set *once*
///      only, the first time that it is accessed (i.e., it is not a dynamic
///      category).  This macro must be used, at most once, within the
///      definition of a class or class template (or else a compiler diagnostic
///      will result).  Note that use of this macro may occur in either a
///      `public`, `private`, or `protected` section of a class's interface,
///      although `private` should be preferred.  Also note that this macro
///      provides the legacy non-hierarchical behavior; new code should prefer
///      `BALL_LOG_SET_CLASS_CATEGORY`.
///
/// Note that similar to block-scope categories (see `BALL_LOG_SET_CATEGORY`,
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`, `BALL_LOG_SET_LEGACY_CATEGORY`, and
/// `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY`), class-scope categories are not
/// destroyed until the logger manager singleton is destroyed.
///
/// ### Macro for Defining Categories at Namespace or Global Scope {#ball_log-macro-for-defining-categories-at-namespace-or-global-scope}
///
///
/// The following macros are used to establish logging categories that have
/// namespace or global scope:
///
/// * `BALL_LOG_SET_NAMESPACE_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the namespace (or global)
///      scope within which this macro is used, using hierarchical category
///      creation.  Similar to `BALL_LOG_SET_CATEGORY`, the category is set
///      *once* only, the first time that it is accessed (i.e., it is not a
///      dynamic category).  This macro may be used, in `.cpp` files *only*, at
///      most once in any given namespace and at most once at global scope (or
///      else a compiler diagnostic will result).  Do *NOT* use this macro in
///      `.h` files.  Note that this macro uses hierarchical category creation;
///      use `BALL_LOG_SET_LEGACY_NAMESPACE_CATEGORY` for the legacy
///      non-hierarchical behavior.
///
/// * `BALL_LOG_SET_LEGACY_NAMESPACE_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the namespace (or global)
///      scope within which this macro is used, using non-hierarchical category
///      creation.  Similar to `BALL_LOG_SET_LEGACY_CATEGORY`, the category is
///      set *once* only, the first time that it is accessed (i.e., it is not a
///      dynamic category).  This macro may be used, in `.cpp` files *only*, at
///      most once in any given namespace and at most once at global scope (or
///      else a compiler diagnostic will result).  Do *NOT* use this macro in
///      `.h` files.  Note that this macro provides the legacy non-hierarchical
///      behavior; new code should prefer `BALL_LOG_SET_NAMESPACE_CATEGORY`.
///
/// Note that similar to block-scope categories (see `BALL_LOG_SET_CATEGORY`,
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`, `BALL_LOG_SET_LEGACY_CATEGORY`, and
/// `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY`), namespace-scope categories are not
/// destroyed until the logger manager singleton is destroyed.
///
/// Note that similar to block-scope categories (see `BALL_LOG_SET_CATEGORY` and
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`), namespace-scope categories are not
/// destroyed until the logger manager singleton is destroyed.
///
/// ### Deprecated Macros for Hierarchical Categories {#ball_log-deprecated-macros-for-hierarchical-categories}
///
///
/// !DEPRECATED! The following macros are deprecated and should not be used in
/// new code.  They were introduced when hierarchical category creation was
/// significantly slower than non-hierarchical creation, providing an explicit
/// opt-in for hierarchical behavior.  Now that performance has been optimized
/// and hierarchical category creation is the default, these macros are
/// redundant with the standard category macros (`BALL_LOG_SET_CATEGORY`,
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`, `BALL_LOG_SET_CLASS_CATEGORY`, and
/// `BALL_LOG_SET_NAMESPACE_CATEGORY`), which now use hierarchical creation by
/// default.  These deprecated macros are maintained only for backward
/// compatibility with existing code.
///
/// * `BALL_LOG_SET_CATEGORY_HIERARCHICALLY(CATEGORY)` !DEPRECATED!
///      Use `BALL_LOG_SET_CATEGORY(CATEGORY)` instead.
///      This macro is identical to `BALL_LOG_SET_CATEGORY`, which now uses
///      hierarchical category creation by default.
///
/// * `BALL_LOG_SET_DYNAMIC_CATEGORY_HIERARCHICALLY(CATEGORY)` !DEPRECATED!
///      Use `BALL_LOG_SET_DYNAMIC_CATEGORY(CATEGORY)` instead.
///      This macro is identical to `BALL_LOG_SET_DYNAMIC_CATEGORY`, which now
///      uses hierarchical category creation by default.
///
/// * `BALL_LOG_SET_CLASS_CATEGORY_HIERARCHICALLY(CATEGORY)` !DEPRECATED!
///      Use `BALL_LOG_SET_CLASS_CATEGORY(CATEGORY)` instead.
///      This macro is identical to `BALL_LOG_SET_CLASS_CATEGORY`, which now
///      uses hierarchical category creation by default.
///
/// * `BALL_LOG_SET_NAMESPACE_CATEGORY_HIERARCHICALLY(CATEGORY)` !DEPRECATED!
///      Use `BALL_LOG_SET_NAMESPACE_CATEGORY(CATEGORY)` instead.
///      This macro is identical to `BALL_LOG_SET_NAMESPACE_CATEGORY`, which now
///      uses hierarchical category creation by default.
///
/// ### Macros for Defining Legacy Non-Hierarchical Categories {#ball_log-macros-for-defining-legacy-non-hierarchical-categories}
///
///
/// The following macros preserve the legacy non-hierarchical category creation
/// behavior for backward compatibility.  These macros use
/// `ball::Log::setCategory` instead of `ball::Log::setCategoryHierarchically`,
/// which means new categories will use the logger manager's default threshold
/// levels rather than inheriting from parent categories.  New code should
/// prefer the standard macros (`BALL_LOG_SET_CATEGORY`, etc.) which use
/// hierarchical category creation by default.
///
/// * `BALL_LOG_SET_LEGACY_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) using non-hierarchical category
///      creation.  This macro provides the legacy behavior where
///      `ball::Log::setCategory` is called instead of
///      `ball::Log::setCategoryHierarchically`.  This macro must be used at
///      block scope, and can be used at most once in any given block (or else
///      a compiler diagnostic will result).
///
/// * `BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY(CATEGORY)`:
///      Set, *on* *EACH* *invocation*, a category for logging to the specified
///      `CATEGORY` using non-hierarchical category creation.  This macro
///      provides the legacy behavior where `ball::Log::setCategory` is called
///      on every invocation instead of `ball::Log::setCategoryHierarchically`.
///      This macro must be used at block scope and can be used at most once in
///      any given block (or else a compiler diagnostic will result).
///
/// * `BALL_LOG_SET_LEGACY_CLASS_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the scope of the class within
///      which this macro is used, using non-hierarchical category creation.
///      This macro provides the legacy behavior where `ball::Log::setCategory`
///      is called instead of `ball::Log::setCategoryHierarchically`.  This
///      macro must be used, at most once, within the definition of a class or
///      class template (or else a compiler diagnostic will result).
///
/// * `BALL_LOG_SET_LEGACY_NAMESPACE_CATEGORY(CATEGORY)`:
///      Set a category for logging to the specified `CATEGORY` (assumed to be
///      of type convertible to `const char *`) in the namespace (or global)
///      scope within which this macro is used, using non-hierarchical category
///      creation.  This macro provides the legacy behavior where
///      `ball::Log::setCategory` is called instead of
///      `ball::Log::setCategoryHierarchically`.  This macro may be used, in
///      `.cpp` files *only*, at most once in any given namespace and at most
///      once at global scope (or else a compiler diagnostic will result).  Do
///      *NOT* use this macro in `.h` files.
///
/// ### Macros for Logging Records {#ball_log-macros-for-logging-records}
///
///
/// The macros defined in this subsection are the ones that are actually used to
/// produce log records.  A use of any one of the logging macros requires that a
/// logging category (as established by the macros defined above) be in scope at
/// the point where the macro is used.  Note that the formatted string that is
/// generated for the message attribute of each log record includes the category
/// that is in scope and the filename as established by the standard `__FILE__`
/// macro.
///
/// The code within any logging statement/code block must not produce any side
/// effects because it may or may not be executed based on run-time
/// configuration of the `ball` logging subsystem:
/// @code
/// BALL_LOG_INFO << ++i;    // (!) May or may not be incremented
///
/// BALL_LOG_TRACE_BLOCK {
///    processRequest(...);  // (!) May or may not be called
/// }
/// @endcode
///
/// A set of macros based on C++ streams, `BALL_LOG_TRACE`, `BALL_LOG_DEBUG`,
/// `BALL_LOG_INFO`, `BALL_LOG_WARN`, `BALL_LOG_ERROR`, and `BALL_LOG_FATAL`,
/// are the ones most commonly used for logging.  They have the following usage
/// pattern:
/// @code
/// BALL_LOG_TRACE << X << Y ... ;
/// BALL_LOG_DEBUG << X << Y ... ;
/// BALL_LOG_INFO  << X << Y ... ;
/// BALL_LOG_WARN  << X << Y ... ;
/// BALL_LOG_ERROR << X << Y ... ;
/// BALL_LOG_FATAL << X << Y ... ;
///     where X, Y, ... represents any sequence of values for which
///     `operator<<` is defined.  The resulting formatted message string is
///     logged with the severity indicated by the name of the macro
///     (e.g., `BALL_LOG_TRACE` logs with severity `ball::Severity::e_TRACE`).
/// @endcode
/// A closely-related macro also based on C++ streams, `BALL_LOG_STREAM`,
/// requires that the severity be explicitly supplied as an argument:
/// @code
/// BALL_LOG_STREAM(SEVERITY) << X << Y ... ;
///     where X, Y, ... represents any sequence of values for which
///     `operator<<` is defined.  The resulting formatted message string is
///     logged with the specified `SEVERITY`.
/// @endcode
/// Another set of macros based on C++ streams, similar to `BALL_LOG_TRACE`,
/// etc., allow the caller to specify a "callback" function that is passed the
/// `ball::UserFields *` used to represent the user fields of a log record.
/// `BALL_LOGCB_TRACE`, `BALL_LOGCB_DEBUG`, `BALL_LOGCB_INFO`,
/// `BALL_LOGCB_WARN`, `BALL_LOGCB_ERROR`, and `BALL_LOGCB_FATAL` have the
/// following usage pattern:
/// @code
/// BALL_LOGCB_TRACE(CALLBACK) << X << Y ... ;
/// BALL_LOGCB_DEBUG(CALLBACK) << X << Y ... ;
/// BALL_LOGCB_INFO(CALLBACK)  << X << Y ... ;
/// BALL_LOGCB_WARN(CALLBACK)  << X << Y ... ;
/// BALL_LOGCB_ERROR(CALLBACK) << X << Y ... ;
/// BALL_LOGCB_FATAL(CALLBACK) << X << Y ... ;
///     where X, Y, ... represents any sequence of values for which
///     `operator<<` is defined and `CALLBACK` is a callback taking a
///     `ball::UserFields *` as an argument.  The resulting formatted message
///     string is logged with the severity indicated by the name of the macro
///     (e.g., `BALL_LOGCB_ERROR` logs with severity
///     `ball::Severity::e_ERROR`).  The generated log record will contain the
///     `ball::UserFields` representing user fields as populated by `CALLBACK`.
///     Note that the callback supplied to the logging macro must match the
///     prototype `void (*)(ball::UserFields *)`.
/// @endcode
/// A closely-related macro also based on C++ streams, `BALL_LOGCB_STREAM`,
/// requires that the severity be explicitly supplied as an argument:
/// @code
/// BALL_LOGCB_STREAM(SEVERITY, CALLBACK) << X << Y ... ;
///     where X, Y, ... represents any sequence of values for which
///     `operator<<` is defined.  The resulting formatted message string is
///     logged with the specified `SEVERITY`.  The generated log record will
///     contain the `ball::UserFields` representing user fields as populated by
///     `CALLBACK`.  Note that the callback supplied to the logging macro must
///     match the prototype `void (*)(ball::UserFields *)`.
/// @endcode
/// The remaining macros are based on `printf`-style format specifications:
/// @code
/// BALL_LOGVA_TRACE(MSG, ...);
/// BALL_LOGVA_DEBUG(MSG, ...);
/// BALL_LOGVA_INFO( MSG, ...);
/// BALL_LOGVA_WARN( MSG, ...);
/// BALL_LOGVA_ERROR(MSG, ...);
/// BALL_LOGVA_FATAL(MSG, ...);
///     Format the specified `...` optional arguments, if any, according to the
///     `printf`-style format specification in the specified `MSG` (assumed to
///     be of type convertible to `const char *`) and log the resulting
///     formatted message string with the severity indicated by the name of the
///     macro (e.g., `BALL_LOGVA_INFO` logs with severity
///     `ball::Severity::e_INFO`).  The behavior is undefined unless the number
///     and types of optional arguments are compatible with the format
///     specification in `MSG`.  Note that each use of these macros must be
///     terminated by a `;`.
/// @endcode
/// A closely-related `printf`-style macro, `BALL_LOGVA`, requires that the
/// severity be explicitly supplied as an argument:
/// @code
/// BALL_LOGVA(SEVERITY, MSG, ...);
///     Format the specified `...` optional arguments, if any, according to the
///     `printf`-style format specification in the specified `MSG` (assumed to
///     be of type convertible to `const char *`) and log the resulting
///     formatted message string with the specified `SEVERITY`.  The behavior
///     is undefined unless the number and types of optional arguments are
///     compatible with the format specification in `MSG`.  Note that each use
///     of this macro must be terminated by a `;`.
/// @endcode
///
/// ### Macros for Logging Code Blocks {#ball_log-macros-for-logging-code-blocks}
///
///
///  The following macros allow the caller to start a code block that will be
///  conditionally executed depending on the current logging threshold of the
///  category that is in scope of those macros:
/// @code
/// BALL_LOG_TRACE_BLOCK { ... }
/// BALL_LOG_DEBUG_BLOCK { ... }
/// BALL_LOG_INFO_BLOCK  { ... }
/// BALL_LOG_WARN_BLOCK  { ... }
/// BALL_LOG_ERROR_BLOCK { ... }
/// BALL_LOG_FATAL_BLOCK { ... }
/// @endcode
/// A closely-related macro, `BALL_LOG_STREAM_BLOCK`, requires that the severity
/// be explicitly supplied as an argument:
/// @code
/// BALL_LOG_STREAM_BLOCK(SEVERITY) { ... }
/// @endcode
/// Another set of macros, similar to `BALL_LOG_*_BLOCK`, allow the caller to
/// specify a "callback" function that is passed the `ball::UserFields *` used
/// to represent the user fields of a log record:
/// @code
/// BALL_LOGCB_TRACE_BLOCK(CALLBACK) { ... }
/// BALL_LOGCB_DEBUG_BLOCK(CALLBACK) { ... }
/// BALL_LOGCB_INFO_BLOCK(CALLBACK)  { ... }
/// BALL_LOGCB_WARN_BLOCK(CALLBACK)  { ... }
/// BALL_LOGCB_ERROR_BLOCK(CALLBACK) { ... }
/// BALL_LOGCB_FATAL_BLOCK(CALLBACK) { ... }
/// @endcode
/// A closely-related macro, `BALL_LOGCB_STREAM_BLOCK`, requires that the
/// severity be explicitly supplied as an argument:
/// @code
/// BALL_LOGCB_STREAM_BLOCK(SEVERITY, CALLBACK) { ... }
/// @endcode
///  Within the logging code block a special macro, `BALL_LOG_OUTPUT_STREAM`,
///  provides access to the log stream.
///
/// ### Utility Macros {#ball_log-utility-macros}
///
///
/// The following utility macro is intended for special-purpose use for
/// fine-tuning logging behavior.  A use of this macro requires that a logging
/// category (as established by the macros defined above) be in scope at the
/// point where the macro is used.
/// @code
/// BALL_LOG_IS_ENABLED(SEVERITY)
///     Return `true` if the specified `SEVERITY` is at least as severe as any
///     of the threshold levels of the logging category that is in scope, and
///     `false` otherwise.
/// @endcode
///
/// ## Usage {#ball_log-usage}
///
///
/// The following code fragments illustrate the standard pattern of macro usage.
///
/// ### Example 1: A Basic Logging Example {#ball_log-example-1-a-basic-logging-example}
///
///
/// The following trivial example shows how to use the logging macros to log
/// messages at various levels of severity.
///
/// First, we initialize the log category within the context of this function.
/// The logging macros such as `BALL_LOG_ERROR` will not compile unless a
/// category has been specified in the current lexical scope:
/// @code
/// BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
/// @endcode
/// Then, we record messages at various levels of severity.  These messages will
/// be conditionally written to the log depending on the current logging
/// threshold of the category (configured using the `ball::LoggerManager`
/// singleton):
/// @code
/// BALL_LOG_FATAL << "Write this message to the log if the log threshold "
///                << "is above 'ball::Severity::e_FATAL' (i.e., 32).";
///
/// BALL_LOG_TRACE << "Write this message to the log if the log threshold "
///                << "is above 'ball::Severity::e_TRACE' (i.e., 192).";
/// @endcode
/// Next, we demonstrate how to use proprietary code within logging macros.
/// Suppose you want to add the content of a vector to the log trace:
/// @code
/// bsl::vector<int> myVector(4, 328);
/// BALL_LOG_TRACE_BLOCK {
///     BALL_LOG_OUTPUT_STREAM << "myVector = [ ";
///     unsigned int position = 0;
///     for (bsl::vector<int>::const_iterator it  = myVector.begin(),
///                                           end = myVector.end();
///         it != end;
///         ++it, ++position) {
///         BALL_LOG_OUTPUT_STREAM << position << ':' << *it << ' ';
///     }
///     BALL_LOG_OUTPUT_STREAM << ']';
/// }
/// @endcode
/// Note that the code block will be conditionally executed depending on the
/// current logging threshold of the category.  The code within the block must
/// not produce any side effects, because its execution depends on the current
/// logging configuration.  The special macro `BALL_LOG_OUTPUT_STREAM` provides
/// access to the log stream within the block.
///
/// ### Example 2: Setting the Current Log Category {#ball_log-example-2-setting-the-current-log-category}
///
///
/// This example provides more detail on setting the log category in the
/// current lexical scope.  The following macro instantiation sets the category
/// for logging to be "EQUITY.NASD" in the enclosing lexical scope:
/// @code
/// BALL_LOG_SET_CATEGORY("EQUITY.NASD")
/// @endcode
/// Note that this macro must not be used at file scope and it can be used at
/// most once in any given block (or else a compiler diagnostic will result).  A
/// different category may be established to override one that is in effect, but
/// it must occur in a nested scope.  In any case, a use of this macro (or of
/// `BALL_LOG_SET_DYNAMIC_CATEGORY`) must be visible from within the lexical
/// scope of every use of the log-generating macros.  The following fragment of
/// code shows how to set a different category in a nested inner block that
/// hides a category set in an enclosing block:
/// @code
/// void logIt()
/// {
///     BALL_LOG_SET_CATEGORY("EQUITY.NASD")
///
///     // Logging to category "EQUITY.NASD" unless overridden in a nested
///     // block.
///     // [*] ...
///
///     {
///         // [*] ...
///         // Still logging to category "EQUITY.NASD".
///
///         BALL_LOG_SET_CATEGORY("EQUITY.NASD.SUNW")
///
///         // Now logging to category "EQUITY.NASD.SUNW".  When this category
///         // is created, it automatically inherits threshold levels from the
///         // existing "EQUITY.NASD" category (the longest prefix match).
///         // [*] ...
///     }
///     // Again logging to category "EQUITY.NASD".
///     // [*] ...
/// }
/// @endcode
/// Within `logIt`, a requisite logging category is visible at each of the
/// locations marked by `[*]`.
///
/// Note that `BALL_LOG_SET_CATEGORY` creates categories *hierarchically*: when
/// a new category is created, its threshold levels are inherited from the
/// orphaned threshold setting or existing category whose name is the longest
/// matching prefix.  In the example above, if "EQUITY.NASD" has been configured
/// with specific threshold levels (either as an existing category or via
/// `setThresholdLevelsHierarchically` before the category exists),
/// "EQUITY.NASD.SUNW" will automatically inherit those thresholds rather than
/// using the logger manager's default levels.  This enables natural
/// configuration of logging for related subsystems.
///
/// ### Example 3: C++ IO Streams-Style Logging Macros {#ball_log-example-3-c-io-streams-style-logging-macros}
///
///
/// The preferred logging method we use, the `iostream`-style macros such as
/// `BALL_LOG_INFO`, allow streaming via the `bsl::ostream` `class` and the C++
/// stream operator `<<`.  An advantage the C++ streaming style has over the
/// `printf` style output (shown below in example 4) is that complex types often
/// have the `operator<<(ostream&, const TYPE&)` function overloaded so that
/// they are able to be easily streamed to output.  We demonstrate this here
/// using C++ streaming to stream a `bdlt::Date` to output:
/// @code
/// int         lotSize = 400;
/// const char *ticker  = "SUNW";
/// double      price   = 5.65;
///
/// // Trading on a market that settles 3 days in the future.
///
/// bdlt::Date settle = bdlt::CurrentTime::local().date() + 3;
///
/// BALL_LOG_SET_CATEGORY("EQUITY.NASD")
/// @endcode
/// We are logging with category "EQUITY.NASD", which is configured for a
/// pass-through level of `e_INFO`, from here on.  We output a line using the
/// `BALL_LOG_INFO` macro:
/// @code
/// BALL_LOG_INFO << "[1] " << lotSize
///               << " shares of " << ticker
///               << " sold at " << price
///               << " settlement date " << settle;
/// @endcode
/// The above results in the following single-line message being output:
/// @code
/// <ts> <pid> <tid> INFO x.cpp 1161 EQUITY.NASD [1] 400 shares of SUNW sold
/// at 5.65 settlement date 17FEB2017
/// @endcode
/// `<ts>` is the timestamp, `<pid>` is the process id, `<tid>` is the thread
/// id, `x.cpp` is the expansion of the `__FILE__` macro that is the name of the
/// source file containing the call, 1161 is the line number of the call, and
/// the trailing date following "settlement date" is the value of `settle`.
///
/// Next, we set the category to "EQUITY.NASD.SUNW".  Because we are using
/// `BALL_LOG_SET_CATEGORY` (which creates categories hierarchically), the new
/// "EQUITY.NASD.SUNW" category automatically inherits threshold levels from the
/// orphaned setting or existing category with the longest matching prefix
/// ("EQUITY.NASD" in this case).  Since "EQUITY.NASD" was configured with a
/// pass-through level of `e_INFO`, the child category "EQUITY.NASD.SUNW" also
/// has `e_INFO` pass-through, meaning `e_WARN` (which is more severe) also
/// passes through:
/// @code
/// {
///     BALL_LOG_SET_CATEGORY("EQUITY.NASD.SUNW")
///
///     // Now logging with category "EQUITY.NASD.SUNW", which inherited
///     // threshold levels from "EQUITY.NASD".
///
///     BALL_LOG_WARN << "[2] " << lotSize
///                   << " shares of " << ticker
///                   << " sold at " << price
///                   << " settlement date " << settle;
/// }
/// @endcode
/// The above results in the following message to category "EQUITY.NASD.SUNW":
/// @code
/// <ts> <pid> <tid> WARN x.cpp 1185 EQUITY.NASD.SUNW [2] 400 shares of SUNW
/// sold at 5.65 settlement date 17FEB2017
/// @endcode
/// Now, the category "EQUITY.NASD.SUNW" just went out of scope and category
/// "EQUITY.NASD" is visible again, so it applies to the following:
/// @code
/// BALL_LOG_INFO << "[3] " << lotSize
///               << " shares of " << ticker
///               << " sold at " << price
///               << " settlement date " << settle;
/// @endcode
/// Finally, the above results in the following single-line message being
/// output:
/// @code
/// <ts> <pid> <tid> INFO x.cpp 1198 EQUITY.NASD [3] 400 shares of SUNW sold
/// at 5.65 settlement date 17FEB2017
/// @endcode
/// The settlement date was appended to the message as a simple illustration of
/// the added flexibility provided by the C++ stream-based macros.  This last
/// message was logged to category "EQUITY.NASD" at severity level
/// `ball::Severity::e_INFO`.
///
/// The C++ stream-based macros, as opposed to the `printf`-style macros, ensure
/// at compile-time that no run-time format mismatches will occur.  Use of the
/// stream-based logging style exclusively will likely lead to clearer, more
/// maintainable code with fewer initial defects.
///
/// Note that all uses of the log-generating macros, both `printf`-style and C++
/// stream-based, *must* occur within function scope (i.e., not at file scope).
///
/// ### Example 4: printf-Style Output {#ball_log-example-4-printf-style-output}
///
///
/// In the following example, we expand the `logIt` function (defined above) to
/// log two messages using the `BALL_LOGVA_INFO` logging macro provided by this
/// component.  This variadic macro takes a format string and a variable-length
/// series of arguments, similar to `printf`.
/// @code
/// int         lotSize = 400;
/// const char *ticker  = "SUNW";
/// double      price   = 5.65;
///
/// // Trading on a market that settles 3 days in the future.
///
/// bdlt::Date settleDate = bdlt::CurrentTime::local().date() + 3;
/// @endcode
/// Because we can't easily `printf` complex types like `bdlt::Date` or
/// `bsl::string`, we have to convert `settleDate` to a `const char *`
/// ourselves.  Note that all this additional work was unnecessary in Example 3
/// when we used the C++ `iostream`-style, rather than the `printf`-style,
/// macros.
/// @code
/// bsl::ostringstream  settleOss;
/// settleOss << settleDate;
/// const bsl::string&  settleStr = settleOss.str();
/// const char         *settle    = settleStr.c_str();
/// @endcode
/// We set logging with category "EQUITY.NASD", which was configured for a
/// pass-through severity level of `e_INFO`, and call `BALL_LOGVA_INFO` to print
/// our trade:
/// @code
/// BALL_LOG_SET_CATEGORY("EQUITY.NASD")
///
/// BALL_LOGVA_INFO("[4] %d shares of %s sold at %f settlement date %s\n",
///                 lotSize, ticker, price, settle);
/// @endcode
/// The above results in the following single-line message being output to
/// category "EQUITY.NASD.SUNW" at severity level `ball::Severity::e_INFO`:
/// @code
/// <ts> <pid> <tid> INFO x.cpp 1256 EQUITY.NASD [4] 400 shares of SUNW sold
/// at 5.650000 settlement date 17FEB2017
/// @endcode
/// In the above, `<ts>` is the timestamp, `<pid>` is the process id, `<tid>` is
/// the thread id, `x.cpp` is the expansion of the `__FILE__` macro that is the
/// name of the source file containing the call, and 1256 is the line number of
/// the call.
///
/// Note that the first argument supplied to the `BALL_LOGVA_INFO` macro is a
/// `printf`-style format specification.
///
/// Next, we set the category to "EQUITY.NASD.SUNW", which is configured for a
/// pass-through severity level of `e_INFO`:
/// @code
/// {
///     BALL_LOG_SET_CATEGORY("EQUITY.NASD.SUNW")
///
///     // Now logging with category "EQUITY.NASD.SUNW".
///
///     BALL_LOGVA_WARN("[5] %d shares of %s sold at %f settlement date %s\n",
///                     lotSize, ticker, price, settle);
/// }
/// @endcode
/// The above results in the following single-line message to category
/// "EQUITY.NASD.SUNW":
/// @code
/// <ts> <pid> <tid> WARN x.cpp 1281 EQUITY.NASD.SUNW [5] 400 shares of SUNW
/// sold at 5.650000 settlement date 17FEB2017
/// @endcode
/// Now, the category "EQUITY.NASD.SUNW" just went out of scope and category
/// "EQUITY.NASD" is visible again, so it applies to the following:
/// @code
/// BALL_LOGVA_INFO("[6] %d shares of %s sold at %f settlement date %s\n",
///                 lotSize, ticker, price, settle);
/// @endcode
/// Finally, the above results in the following single-line message being
/// output:
/// @code
/// <ts> <pid> <tid> INFO x.cpp 1294 EQUITY.NASD [6] 400 shares of SUNW sold
/// at 5.650000 settlement date 17FEB2017
/// @endcode
///
/// ### Example 5: Dynamic Categories {#ball_log-example-5-dynamic-categories}
///
///
/// Logging must sometimes be controlled by parameters that are not available
/// until run-time.  The `BALL_LOG_SET_DYNAMIC_CATEGORY` macro sets a category
/// each time it is invoked (unlike `BALL_LOG_SET_CATEGORY`, which sets a
/// category only on the first invocation and uses the cached address of the
/// category on subsequent invocations).  The category name in the following
/// `processSecurity` function is a combination of a static prefix and the
/// (dynamic) `exchange` argument:
/// @code
/// void processSecurity(const char *security, const char *exchange)
/// {
///     bsl::string categoryName("EXCHANGE:");
///     categoryName.append(exchange);
///
///     BALL_LOG_SET_DYNAMIC_CATEGORY(categoryName.c_str());
///
///     BALL_LOG_TRACE << "processing: " << security;
///
///     // ...
/// }
/// @endcode
/// Now logging can be controlled independently for each `exchange`.
///
/// *WARNING*: Along with the added flexibility provided by dynamic categories
/// comes the additional overhead of computing and setting a category on each
/// invocation.  Consequently, dynamic categories should be used *SPARINGLY* in
/// most applications.
///
/// ### Example 6: Rule-Based Logging {#ball_log-example-6-rule-based-logging}
///
///
/// The following example demonstrates the use of attributes and rules to
/// conditionally enable logging.
///
/// We start by defining a function, `processData`, that is passed data in a
/// `vector<char>` and information about the user who sent the data.  This
/// example function performs no actual processing, but does log a single
/// message at the `ball::Severity::e_DEBUG` threshold level.  The `processData`
/// function also adds the user information passed to this function to the
/// thread's attribute context.  We will use these attributes later, to create a
/// logging rule that enables verbose logging only for a particular user.
/// @code
/// /// Process the specified `data` associated with the specified Bloomberg
/// /// `uuid`, `luw`, and `terminalNumber`.
/// void processData(int                      uuid,
///                  int                      luw,
///                  int                      terminalNumber,
///                  const bsl::vector<char>& data)
/// {
///     (void)data;  // suppress "unused" warning
/// @endcode
/// We add our attributes using `ball::ScopedAttribute`, which adds an attribute
/// container with one attribute to a list of containers.  This is easy and
/// efficient if the number of attributes is small, but should not be used if
/// there are a large number of attributes.  If motivated, we could use
/// `ball::DefaultAttributeContainer`, which provides an efficient container for
/// a large number of attributes, or even create a more efficient attribute
/// container implementation specifically for these three attributes (uuid, luw,
/// and terminalNumber).  See @ref ball_scopedattributes  (plural) for an example
/// of using a different attribute container, and @ref ball_attributecontainer 
/// for an example of creating a custom attribute container.
/// @code
///     // We use `ball::ScopedAttribute` here because the number of
///     // attributes is relatively small.
///
///     ball::ScopedAttribute uuidAttribute("mylibrary.uuid", uuid);
///     ball::ScopedAttribute luwAttribute("mylibrary.luw", luw);
///     ball::ScopedAttribute termNumAttribute("mylibrary.terminalNumber",
///                                            terminalNumber);
/// @endcode
/// In this simplified example we perform no actual processing, and simply log
/// a message at the `ball::Severity::e_DEBUG` level.
/// @code
///     BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
///
///     BALL_LOG_DEBUG << "An example message";
/// @endcode
/// Notice that if we were not using a "scoped" attribute container like that
/// provided automatically by `ball::ScopedAttribute` (e.g., if we were using a
/// local `ball::DefaultAttributeContainer` instead), then the container
/// **must** be removed from the `ball::AttributeContext` before it is
/// destroyed!  See @ref ball_scopedattributes  (plural) for an example.
/// @code
/// }
/// @endcode
/// Next we demonstrate how to create a logging rule that sets the pass-through
/// logging threshold to `ball::Severity::e_TRACE` (i.e., enables verbose
/// logging) for a particular user when calling the `processData` function
/// defined above.
///
/// We start by creating the singleton logger manager that we configure with
/// the stream observer and a default configuration.  We then call the
/// `processData` function: This first call to `processData` will not result in
/// any logged messages because `processData` logs its message at the
/// `ball::Severity::e_DEBUG` level, which is below the default configured
/// logging threshold.
/// @code
/// ball::LoggerManagerConfiguration lmConfig;
/// ball::LoggerManagerScopedGuard   lmGuard(lmConfig);
///
/// bsl::shared_ptr<ball::StreamObserver> observer =
///                         bsl::make_shared<ball::StreamObserver>(&bsl::cout);
///
/// ball::LoggerManager::singleton().registerObserver(observer, "default");
///
/// BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
///
/// bsl::vector<char> message;
///
/// BALL_LOG_ERROR << "Processing the first message.";
/// processData(3938908, 2, 9001, message);
/// @endcode
/// Now we add a logging rule, setting the pass-through threshold to be
/// `ball::Severity::e_TRACE` (i.e., enabling verbose logging) if the thread's
/// context contains an attribute with name "mylibrary.uuid" with value 3938908.
/// Note that we use the wild-card value `*` for the category so that the
/// `ball::Rule` rule will apply to all categories. Also note that the computation of
/// effective threshold levels for **every** category matching the pattern has
/// considerable performance implications.
/// @code
/// ball::Rule rule("*", 0, ball::Severity::e_TRACE, 0, 0);
/// rule.addAttribute(ball::ManagedAttribute("mylibrary.uuid", 3938908));
/// ball::LoggerManager::singleton().addRule(rule);
///
/// BALL_LOG_ERROR << "Processing the second message.";
/// processData(3938908, 2, 9001, message);
/// @endcode
/// The final call to the `processData` function below, passes a `uuid` of
/// 2171395 (not 3938908) so the logging rule we defined will *not* apply and no
/// message will be logged.
/// @code
/// BALL_LOG_ERROR << "Processing the third message.";
/// processData(2171395, 2, 9001, message);
/// @endcode
/// The resulting logged output for this example looks like the following:
/// @code
/// ERROR example.cpp:105 EXAMPLE.CATEGORY Processing the first message.
/// ERROR example.cpp:117 EXAMPLE.CATEGORY Processing the second message.
/// DEBUG example.cpp:35 EXAMPLE.CATEGORY An example message
/// ERROR example.cpp:129 EXAMPLE.CATEGORY Processing the third message.
/// @endcode
///
/// ### Example 7: Logging Using a Callback {#ball_log-example-7-logging-using-a-callback}
///
///
/// The following example demonstrates how to register a logging callback.  The
/// C++ stream-based macros that take a callback are particularly useful to
/// seamlessly populate the user fields of a record, thus simplifying the
/// logging line.
///
/// We define a callback function `populateUsingPoint` that appends to the
/// specified `fields` the attributes of the `point` to log:
/// @code
/// /// Append to the specified `list` the name, x value, and y value of
/// /// the specified `point`.
/// void populateUsingPoint(ball::UserFields *fields, const Point& point)
/// {
///     fields->appendString(point.name());
///     fields->appendInt64(point.x());
///     fields->appendInt64(point.y());
/// }
///
/// int validatePoint(const Point& point)
/// {
///     BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
/// @endcode
/// We now bind our callback function `populateUsingPoint` and the supplied
/// `point` to a functor object we will pass to the logging callback.  Note
/// that the callback supplied to the logging macro must match the prototype
/// `void (*)(ball::UserFields *)`.
/// @code
///     bsl::function <void(ball::UserFields *)> callback;
///     callback = bdlf::BindUtil::bind(&populateUsingPoint,
///                                     bdlf::PlaceHolders::_1,
///                                     point);
///
///     int numErrors = 0;
///     if (point.x() > 255) {
///         BALL_LOGCB_ERROR(callback) << "X > 255";
///         ++numErrors;
///     }
///     if (point.x() < -255) {
///         BALL_LOGCB_ERROR(callback) << "X < -255";
///         ++numErrors;
///     }
///     if (point.y() > 255) {
///         BALL_LOGCB_ERROR(callback) << "Y > 255";
///         ++numErrors;
///     }
///     if (point.y() < -255) {
///         BALL_LOGCB_ERROR(callback) << "Y < -255";
///         ++numErrors;
///     }
///     return numErrors;
/// }
/// @endcode
///
/// ### Example 8: Class-Scope Logging {#ball_log-example-8-class-scope-logging}
///
///
/// The following example demonstrates how to define and use logging categories
/// that have class scope.
///
/// First, we define a class, `Thing`, for which we want to do class-scope
/// logging.  The use of the `BALL_LOG_SET_CLASS_CATEGORY` macro generates the
/// requisite declarations within the definition of the class.  We have used the
/// macro in a `private` section of the interface, which should be preferred,
/// but `public` (or `protected`) is fine, too:
/// @code
/// // pckg_thing.h
/// namespace pckg {
///
/// class Thing {
///     // ...
///
///   private:
///     BALL_LOG_SET_CLASS_CATEGORY("PCKG.THING");
///
///   public:
///     // ...
///
///     // MANIPULATORS
///
///     /// Log to the class-scope category "PCKG.THING" if the specified
///     /// `useClassCategory` flag is `true`, and to the block-scope
///     /// category "X.Y.Z" otherwise.
///     void outOfLineMethodThatLogs(bool useClassCategory);
///
///     // ...
///
///     // ACCESSORS
///
///     /// Log a record to the class-scope category "PCKG.THING".
///     void inlineMethodThatLogs() const;
/// };
/// @endcode
/// Next, we define the `inlineMethodThatLogs` method `inline` within the header
/// file and log to the class-scope category using `BALL_LOG_TRACE`.  Since
/// there is no other category in scope, the record is necessarily logged to the
/// "PCKG.THING" category that is within the scope of the `Thing` class:
/// @code
/// // ...
///
/// // ACCESSORS
/// inline
/// void Thing::inlineMethodThatLogs() const
/// {
///     BALL_LOG_TRACE << "log to PCKG.THING";
/// }
///
/// }  // close namespace pckg
/// @endcode
/// Now, we define the `outOfLineMethodThatLogs` method within the `.cpp` file.
/// On each invocation, this method logs one record using `BALL_LOG_TRACE`.  It
/// logs to the "PCKG.THING" class-scope category if `useClassCategory` is
/// `true`, and logs to the "X.Y.Z" block-scope category otherwise:
/// @code
/// // pckg_thing.cpp
/// namespace pckg {
///
/// // ...
///
/// // MANIPULATORS
/// void Thing::outOfLineMethodThatLogs(bool useClassCategory)
/// {
///     if (useClassCategory) {
///         BALL_LOG_TRACE << "log to PCKG.THING";
///     }
///     else {
///         BALL_LOG_SET_CATEGORY("X.Y.Z");
///         BALL_LOG_TRACE << "log to X.Y.Z";
///     }
/// }
///
/// }  // close namespace pckg
/// @endcode
/// Finally, note that both block-scope and class-scope categories can be logged
/// to within the same block.  For example, the following block within a `Thing`
/// method would first log to "PCKG.THING" then log to "X.Y.Z":
/// @code
///     {
///         BALL_LOG_TRACE << "log to PCKG.THING";
///
///         BALL_LOG_SET_CATEGORY("X.Y.Z");
///
///         BALL_LOG_TRACE << "log to X.Y.Z";
///     }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup ball
 * @{
 */
/** @addtogroup ball_log
 * @{
 */
 
#include <balscm_version.h>
 
#include <ball_category.h>
#include <ball_categorymanager.h>
#include <ball_loggermanager.h>
#include <ball_severity.h>
 
#include <bslma_managedptr.h>
 
#include <bsls_annotation.h>
#include <bsls_keyword.h>
#include <bsls_performancehint.h>
#include <bsls_platform.h>
 
#include <bsl_ostream.h>
 
#include <bslmt_mutex.h>
 
                       // =========================
                       // Logging Macro Definitions
                       // =========================
 
#define BALL_LOG_CATEGORY                                                     \
    (ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER)->category())
 
#define BALL_LOG_THRESHOLD                                                    \
    (ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER)->threshold())
 
#define BALL_LOG_RECORD (ball_log_lOg_StReAm.record())
 
#define BALL_LOG_OUTPUT_STREAM (ball_log_lOg_StReAm.stream())
 
                       // ===========================
                       // Block-Scope Category Macros
                       // ===========================
 
#define BALL_LOG_SET_CATEGORY(CATEGORY)                                       \
    static BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {      \
        { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },      \
                                                             { 0 }, { 0 }     \
    };                                                                        \
    if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!BALL_LOG_CATEGORY)) {          \
        BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                                   \
        BloombergLP::ball::Log::setCategoryHierarchically(                    \
                                            &BALL_LOG_CATEGORYHOLDER,         \
                                            CATEGORY);                        \
    }
 
#define BALL_LOG_SET_LEGACY_CATEGORY(CATEGORY)                                \
    static BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {      \
        { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },      \
                                                             { 0 }, { 0 }     \
    };                                                                        \
    if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!BALL_LOG_CATEGORY)) {          \
        BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                                   \
        BloombergLP::ball::Log::setCategory(&BALL_LOG_CATEGORYHOLDER,         \
                                            CATEGORY);                        \
    }
 
#define BALL_LOG_SET_CATEGORY_HIERARCHICALLY(CATEGORY)                        \
    static BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {      \
        { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },      \
                                                             { 0 }, { 0 }     \
    };                                                                        \
    if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!BALL_LOG_CATEGORY)) {          \
        BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                                   \
        BloombergLP::ball::Log::setCategoryHierarchically(                    \
                                            &BALL_LOG_CATEGORYHOLDER,         \
                                            CATEGORY);                        \
    }
 
#define BALL_LOG_SET_DYNAMIC_CATEGORY(CATEGORY)                               \
    const BloombergLP::ball::Category *BALL_LOG_DYNAMIC_CATEGORY =            \
                 BloombergLP::ball::Log::setCategoryHierarchically(CATEGORY); \
    BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {             \
        { BloombergLP::ball::CategoryHolder::e_DYNAMIC_CATEGORY },            \
        { const_cast<BloombergLP::ball::Category *>(                          \
                                                BALL_LOG_DYNAMIC_CATEGORY) }, \
        { 0 }                                                                 \
    };
 
#define BALL_LOG_SET_LEGACY_DYNAMIC_CATEGORY(CATEGORY)                        \
    const BloombergLP::ball::Category *BALL_LOG_DYNAMIC_CATEGORY =            \
                               BloombergLP::ball::Log::setCategory(CATEGORY); \
    BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {             \
        { BloombergLP::ball::CategoryHolder::e_DYNAMIC_CATEGORY },            \
        { const_cast<BloombergLP::ball::Category *>(                          \
                                                BALL_LOG_DYNAMIC_CATEGORY) }, \
        { 0 }                                                                 \
    };
 
#define BALL_LOG_SET_DYNAMIC_CATEGORY_HIERARCHICALLY(CATEGORY)                \
    const BloombergLP::ball::Category *BALL_LOG_DYNAMIC_CATEGORY =            \
                 BloombergLP::ball::Log::setCategoryHierarchically(CATEGORY); \
    BloombergLP::ball::CategoryHolder BALL_LOG_CATEGORYHOLDER = {             \
        { BloombergLP::ball::CategoryHolder::e_DYNAMIC_CATEGORY },            \
        { const_cast<BloombergLP::ball::Category *>(                          \
                                                BALL_LOG_DYNAMIC_CATEGORY) }, \
        { 0 }                                                                 \
    };
 
                       // ===========================
                       // Class-Scope Category Macros
                       // ===========================
 
#define BALL_LOG_SET_CLASS_CATEGORY(CATEGORY)                                 \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(      \
                     const BloombergLP::ball::CategoryHolder& categoryHolder) \
    {                                                                         \
        return &categoryHolder;                                               \
    }                                                                         \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategoryHierarchically(&holder,        \
                                                              CATEGORY);      \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 }
 
#define BALL_LOG_SET_LEGACY_CLASS_CATEGORY(CATEGORY)                          \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(      \
                     const BloombergLP::ball::CategoryHolder& categoryHolder) \
    {                                                                         \
        return &categoryHolder;                                               \
    }                                                                         \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategory(&holder, CATEGORY);           \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 }
 
#define BALL_LOG_SET_CLASS_CATEGORY_HIERARCHICALLY(CATEGORY)                  \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(      \
                     const BloombergLP::ball::CategoryHolder& categoryHolder) \
    {                                                                         \
        return &categoryHolder;                                               \
    }                                                                         \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategoryHierarchically(&holder,        \
                                                              CATEGORY);      \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 }
 
                       // ===============================
                       // Namespace-Scope Category Macros
                       // ===============================
 
#define BALL_LOG_SET_NAMESPACE_CATEGORY(CATEGORY)                             \
namespace {                                                                   \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategoryHierarchically(&holder,        \
                                                              CATEGORY);      \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 };                                     \
}
 
#define BALL_LOG_SET_LEGACY_NAMESPACE_CATEGORY(CATEGORY)                      \
namespace {                                                                   \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategory(&holder, CATEGORY);           \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 };                                     \
}
 
#define BALL_LOG_SET_NAMESPACE_CATEGORY_HIERARCHICALLY(CATEGORY)              \
namespace {                                                                   \
    static                                                                    \
    const BloombergLP::ball::CategoryHolder *ball_log_getCategoryHolder(int)  \
    {                                                                         \
        static BloombergLP::ball::CategoryHolder holder = {                   \
            { BloombergLP::ball::CategoryHolder::e_UNINITIALIZED_CATEGORY },  \
                                                                 { 0 }, { 0 } \
        };                                                                    \
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(!holder.category())) {      \
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;                               \
            BloombergLP::ball::Log::setCategoryHierarchically(&holder,        \
                                                              CATEGORY);      \
        }                                                                     \
        return &holder;                                                       \
    }                                                                         \
    enum { BALL_LOG_CATEGORYHOLDER = 0 };                                     \
}
 
                 // ====================================
                 // Implementation Details: Do *NOT* Use
                 // ====================================
 
// BALL_LOG_STREAM_CONST_IMP requires its argument to be a compile-time
// constant.
 
#define BALL_LOG_STREAM_CONST_IMP(SEVERITY)                                   \
for (const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =       \
               BloombergLP::ball::Log::categoryHolderIfEnabled<(SEVERITY)>(   \
                        ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER)); \
     ball_log_cAtEgOrYhOlDeR;                                                 \
     )                                                                        \
for (BloombergLP::ball::Log_Stream ball_log_lOg_StReAm(                       \
                                         ball_log_cAtEgOrYhOlDeR->category(), \
                                         __FILE__,                            \
                                         __LINE__,                            \
                                         (SEVERITY));                         \
     ball_log_cAtEgOrYhOlDeR;                                                 \
     ball_log_cAtEgOrYhOlDeR = 0)
 
// BALL_LOG_STREAM_IMP allows its argument to be calculated at run-time, at a
// cost in performance.
 
#define BALL_LOG_STREAM_IMP(SEVERITY)                                         \
for (const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =       \
                         ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER); \
     ball_log_cAtEgOrYhOlDeR                                                  \
     && ball_log_cAtEgOrYhOlDeR->threshold() >= (SEVERITY)                    \
     && BloombergLP::ball::Log::isCategoryEnabled(ball_log_cAtEgOrYhOlDeR,    \
                                                  (SEVERITY));                \
     )                                                                        \
for (BloombergLP::ball::Log_Stream ball_log_lOg_StReAm(                       \
                                         ball_log_cAtEgOrYhOlDeR->category(), \
                                         __FILE__,                            \
                                         __LINE__,                            \
                                         (SEVERITY));                         \
     ball_log_cAtEgOrYhOlDeR;                                                 \
     ball_log_cAtEgOrYhOlDeR = 0)
 
                       // =======================
                       // C++ stream-based macros
                       // =======================
 
#define BALL_LOG_STREAM(SEVERITY)                                             \
    BALL_LOG_STREAM_IMP((SEVERITY)) BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_TRACE                                                        \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_TRACE)           \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_DEBUG                                                        \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_DEBUG)           \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_INFO                                                         \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_INFO)            \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_WARN                                                         \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_WARN)            \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_ERROR                                                        \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_ERROR)           \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_FATAL                                                        \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_FATAL)           \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOG_STREAM_BLOCK(SEVERITY) BALL_LOG_STREAM_IMP((SEVERITY))
 
#define BALL_LOG_TRACE_BLOCK                                                  \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_TRACE)
 
#define BALL_LOG_DEBUG_BLOCK                                                  \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_DEBUG)
 
#define BALL_LOG_INFO_BLOCK                                                   \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_INFO)
 
#define BALL_LOG_WARN_BLOCK                                                   \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_WARN)
 
#define BALL_LOG_ERROR_BLOCK                                                  \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_ERROR)
 
#define BALL_LOG_FATAL_BLOCK                                                  \
    BALL_LOG_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_FATAL)
 
#define BALL_LOG_END ""
 
                    // ====================================
                    // Implementation Details: Do *NOT* Use
                    // ====================================
 
// BALL_LOGCB_STREAM_CONST_IMP requires its first argument to be a compile-time
// constant.
 
#define BALL_LOGCB_STREAM_CONST_IMP(SEVERITY, CALLBACK)                       \
for (const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =       \
               BloombergLP::ball::Log::categoryHolderIfEnabled<(SEVERITY)>(   \
                        ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER)); \
     ball_log_cAtEgOrYhOlDeR;                                                 \
     )                                                                        \
for (BloombergLP::ball::Log_Stream ball_log_lOg_StReAm(                       \
                                         ball_log_cAtEgOrYhOlDeR->category(), \
                                         __FILE__,                            \
                                         __LINE__,                            \
                                         (SEVERITY));                         \
     ball_log_cAtEgOrYhOlDeR                                                  \
     && (CALLBACK(&BALL_LOG_RECORD->customFields()), true);                   \
     ball_log_cAtEgOrYhOlDeR = 0)
 
// BALL_LOGCB_STREAM_IMP allows its first argument to be calculated at
// run-time, at a cost in performance.
 
#define BALL_LOGCB_STREAM_IMP(SEVERITY, CALLBACK)                             \
for (const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =       \
                         ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER); \
     ball_log_cAtEgOrYhOlDeR                                                  \
     && ball_log_cAtEgOrYhOlDeR->threshold() >= (SEVERITY)                    \
     && BloombergLP::ball::Log::isCategoryEnabled(ball_log_cAtEgOrYhOlDeR,    \
                                                  (SEVERITY));                \
     )                                                                        \
for (BloombergLP::ball::Log_Stream ball_log_lOg_StReAm(                       \
                                         ball_log_cAtEgOrYhOlDeR->category(), \
                                         __FILE__,                            \
                                         __LINE__,                            \
                                         (SEVERITY));                         \
     ball_log_cAtEgOrYhOlDeR                                                  \
     && (CALLBACK(&BALL_LOG_RECORD->customFields()), true);                   \
     ball_log_cAtEgOrYhOlDeR = 0)
 
               // ========================================
               // C++ stream-based macros using a callback
               // ========================================
 
#define BALL_LOGCB_STREAM(BALL_SEVERITY, CALLBACK)                            \
    BALL_LOGCB_STREAM_IMP((BALL_SEVERITY), (CALLBACK)) BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_TRACE(CALLBACK)                                            \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_TRACE,         \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_DEBUG(CALLBACK)                                            \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_DEBUG,         \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_INFO(CALLBACK)                                             \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_INFO,          \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_WARN(CALLBACK)                                             \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_WARN,          \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_ERROR(CALLBACK)                                            \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_ERROR,         \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_FATAL(CALLBACK)                                            \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_FATAL,         \
                                (CALLBACK))                                   \
    BALL_LOG_OUTPUT_STREAM
 
#define BALL_LOGCB_STREAM_BLOCK(BALL_SEVERITY, CALLBACK)                      \
    BALL_LOGCB_STREAM_IMP((BALL_SEVERITY), (CALLBACK))
 
#define BALL_LOGCB_TRACE_BLOCK(CALLBACK)                                      \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_TRACE,         \
                                (CALLBACK))
 
#define BALL_LOGCB_DEBUG_BLOCK(CALLBACK)                                      \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_DEBUG,         \
                                (CALLBACK))
 
#define BALL_LOGCB_INFO_BLOCK(CALLBACK)                                       \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_INFO,          \
                                (CALLBACK))
 
#define BALL_LOGCB_WARN_BLOCK(CALLBACK)                                       \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_WARN,          \
                                (CALLBACK))
 
#define BALL_LOGCB_ERROR_BLOCK(CALLBACK)                                      \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_ERROR,         \
                                (CALLBACK))
 
#define BALL_LOGCB_FATAL_BLOCK(CALLBACK)                                      \
    BALL_LOGCB_STREAM_CONST_IMP(BloombergLP::ball::Severity::e_FATAL,         \
                                (CALLBACK))
 
#define BALL_LOGCB_END ""
 
                 // ====================================
                 // Implementation Details: Do *NOT* Use
                 // ====================================
 
// BALL_LOGVA_CONST_IMP requires its first argument to be a compile-time
// constant, while all the others may be variables.
 
#define BALL_LOGVA_CONST_IMP(SEVERITY, ...)                                   \
do {                                                                          \
    if (const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =    \
               BloombergLP::ball::Log::categoryHolderIfEnabled<(SEVERITY)>(   \
                      ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER))) { \
        BloombergLP::ball::Log_Formatter ball_log_fOrMaTtEr(                  \
                                       ball_log_cAtEgOrYhOlDeR->category(),   \
                                       __FILE__,                              \
                                       __LINE__,                              \
                                       (SEVERITY));                           \
        BloombergLP::ball::Log::format(ball_log_fOrMaTtEr.messageBuffer(),    \
                                       ball_log_fOrMaTtEr.messageBufferLen(), \
                                       __VA_ARGS__);                          \
    }                                                                         \
} while(0)
 
                       // =====================
                       // 'printf'-style macros
                       // =====================
 
// BALL_LOGVA allows all its arguments to be calculated at run-time, at a cost
// in performance.
 
#define BALL_LOGVA(SEVERITY, ...)                                             \
do {                                                                          \
    const BloombergLP::ball::CategoryHolder *ball_log_cAtEgOrYhOlDeR =        \
                         ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER); \
    if (ball_log_cAtEgOrYhOlDeR->threshold() >= (SEVERITY) &&                 \
           BloombergLP::ball::Log::isCategoryEnabled(ball_log_cAtEgOrYhOlDeR, \
                                                     (SEVERITY))) {           \
        BloombergLP::ball::Log_Formatter ball_log_fOrMaTtEr(                  \
                                       ball_log_cAtEgOrYhOlDeR->category(),   \
                                       __FILE__,                              \
                                       __LINE__,                              \
                                       (SEVERITY));                           \
        BloombergLP::ball::Log::format(ball_log_fOrMaTtEr.messageBuffer(),    \
                                       ball_log_fOrMaTtEr.messageBufferLen(), \
                                       __VA_ARGS__);                          \
    }                                                                         \
} while(0)
 
#define BALL_LOGVA_TRACE(...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_TRACE, __VA_ARGS__)
 
#define BALL_LOGVA_DEBUG(...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_DEBUG, __VA_ARGS__)
 
#define BALL_LOGVA_INFO( ...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_INFO,  __VA_ARGS__)
 
#define BALL_LOGVA_WARN( ...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_WARN,  __VA_ARGS__)
 
#define BALL_LOGVA_ERROR(...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_ERROR, __VA_ARGS__)
 
#define BALL_LOGVA_FATAL(...)                                                 \
    BALL_LOGVA_CONST_IMP(BloombergLP::ball::Severity::e_FATAL, __VA_ARGS__)
 
                       // ==============
                       // Utility Macros
                       // ==============
 
#define BALL_LOG_IS_ENABLED(SEVERITY)                                         \
    ((BALL_LOG_THRESHOLD >= (SEVERITY))                                       \
     && BloombergLP::ball::Log::isCategoryEnabled(                            \
                         ball_log_getCategoryHolder(BALL_LOG_CATEGORYHOLDER), \
                         (SEVERITY)))
 
 
 
 
namespace ball {
 
// BDE_VERIFY pragma: push
// BDE_VERIFY pragma: -AQQ01
// BDE_VERIFY pragma: -AQS01
// BDE_VERIFY pragma: -FB01
// BDE_VERIFY pragma: -KS00
// BDE_VERIFY pragma: -TR04
// BDE_VERIFY pragma: -TR17
 
                       // =======================
                       // CategoryHolder Accessor
                       // =======================
 
/// Return the address of the specified `categoryHolder`.  
/// \note Note that  this
/// function facilitates consistent lookup of block-scope and class-scope
/// category holders (see "Logging Macro Reuse" in the "IMPLEMENTATION
/// NOTES" of the component implementation file for details).
inline
const BloombergLP::ball::CategoryHolder* ball_log_getCategoryHolder(
                       const BloombergLP::ball::CategoryHolder& categoryHolder)
{
    return &categoryHolder;
}
 
// BDE_VERIFY pragma: pop
 
class Record;
 
                         // ==========
                         // struct Log
                         // ==========
 
/// This `struct` provides a namespace for a suite of utility functions that
/// simplify usage of the @ref ball_loggermanager  component.  The direct use
/// of these utility functions is *strongly* discouraged.
///
/// See @ref ball_log 
struct Log {
 
    // CLASS METHODS
 
    /// Fill the specified `buffer` with at most the specified `numBytes`
    /// characters produced by formatting the variable argument list
    /// according to the specified `printf`-style `format` argument; return
    /// the number of characters in the resulting formatted string.  The
    /// last character placed into `buffer` is always a null terminator
    /// (leaving at most `numBytes - 1` bytes of formatted data).  If
    /// `numBytes` is insufficient for the entire formatted string, this
    /// method fills `buffer` with the initial `numBytes - 1` bytes of
    /// formatted data followed by a null terminator and returns -1.  
    /// 
    /// \note Note that   with the exception of the return value, the behavior of this
    /// function exactly matches that of the C99 function `snprintf`.  Also
    /// note that `snprintf` is not part of standard C++-98, so its
    /// functionality is provided here.
    static int format(char        *buffer,
                      bsl::size_t  numBytes,
                      const char  *format, ...) BSLS_ANNOTATION_PRINTF(3, 4);
 
    /// Return the address of a modifiable record having the specified
    /// `fileName` and `lineNumber` attributes.  The memory for the record
    /// will be supplied by the allocator held by the logger manager
    /// singleton if the specified `category` is non-null, or by the
    /// currently installed default allocator otherwise.  
    /// 
    /// \pre The behavior is undefined   unless the logger manager singleton is initialized when `category` is non-null.  
    /// 
    /// \note Note that   the returned `Record` must
    /// subsequently be supplied to a call to the 3-argument `logMessage`
    /// method.
    static Record *getRecord(const Category          *category,
                             const bsl::string_view&  fileName,
                             int                      lineNumber);
 
    /// Log a record containing the specified `message` text, `fileName`,
    /// `lineNumber`, `severity`, and the name of the specified `category`.
    /// (See the component-level documentation of @ref ball_record  for more
    /// information on the additional fields that are logged.)  Store the
    /// record in the buffer held by the logger if `severity` is at least
    /// as severe as the current "Record" threshold level of `category`.
    /// Pass the record directly to the registered observer if `severity`
    /// is at least as severe as the current "Pass" threshold level of
    /// `category`.  Publish the entire contents of the buffer of the
    /// logger if `severity` is at least as severe as the current "Trigger"
    /// threshold level of `category`.  Publish the entire contents of all
    /// buffers of all loggers if `severity` is at least as severe as the
    /// current "Trigger-All" threshold level of `category` (i.e., via the
    /// callback supplied at construction of the logger manager singleton).
    /// This method has no effect if `category` is 0 or `severity` is less
    /// severe than each of the threshold levels of `category`.  
    /// 
    /// \pre The behavior is undefined   unless `severity` is in the range `[1 .. 255]`
    /// and the logger manager singleton is initialized when `category` is
    /// non-null.
    static void logMessage(const Category          *category,
                           int                      severity,
                           const bsl::string_view&  fileName,
                           int                      lineNumber,
                           const bsl::string_view&  message);
 
    /// Log the specified `record` after setting its category attribute to
    /// the specified `category` and its severity attribute to the specified
    /// `severity`.  (See the component-level documentation of @ref ball_record 
    /// for more information on the fields that are logged.)  Store the
    /// record in the buffer held by the logger if `severity` is at least
    /// as severe as the current "Record" threshold level of `category`.
    /// Pass the record directly to the registered observer if `severity`
    /// is at least as severe as the current "Pass" threshold level of
    /// `category`.  Publish the entire contents of the buffer of the
    /// logger if `severity` is at least as severe as the current "Trigger"
    /// threshold level of `category`.  Publish the entire contents of all
    /// buffers of all loggers if `severity` is at least as severe as the
    /// current "Trigger-All" threshold level of `category` (i.e., via the
    /// callback supplied at construction of the logger manager singleton).
    /// Finally, dispose of `record`.  This method has no effect (other than
    /// disposing of `record`) if `severity` is less severe than each of the threshold levels of `category`.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `severity` is in the range `[1 .. 255]`, `record` was obtained by a
    /// call to `Log::getRecord`, and, if `category` is not 0, the logger manager singleton is initialized.  
    /// 
    /// \note Note that   `record` will be
    /// invalid after this method returns.
    static void logMessage(const Category *category,
                           int             severity,
                           Record         *record);
 
    /// Block until access to the buffer used for formatting messages in
    /// this thread of execution is available.  Return the address of the
    /// modifiable buffer to which this thread of execution has exclusive
    /// access, load the address of the mutex that protects the buffer into
    /// the specified `*mutex` address, and load the size (in bytes) of the
    /// buffer into the specified `bufferSize` address.  The address remains
    /// valid, and the buffer remains locked by this thread of execution,
    /// until the `Log::releaseMessageBuffer` method is called.  
    /// 
    /// \pre The behavior is undefined   if this thread of execution currently holds a lock on the buffer.  
    /// 
    /// \note Note that   the buffer is intended to be used
    /// *only* for formatting log messages immediately before a call to
    /// `Log::logMessage`; other use may adversely affect performance for
    /// the entire program.
    static char *obtainMessageBuffer(bslmt::Mutex **mutex,
                                     int           *bufferSize);
 
    /// Unlock the specified `mutex` that guards the buffer used for
    /// formatting messages in this thread of execution.  
    /// 
    /// \pre The behavior is undefined   unless `mutex` was obtained by a call to
    /// `Log::obtainMessageBuffer` and has not yet been unlocked.
    static void releaseMessageBuffer(bslmt::Mutex *mutex);
 
    /// Return a managed pointer that refers to the memory block to which
    /// this thread of execution has exclusive access and load the size (in
    /// bytes) of this buffer into the specified `bufferSize` address.  
    /// 
    /// \note Note that   this method is intended for *internal* *use* only.
    static bslma::ManagedPtr<char> obtainMessageBuffer(int *bufferSize);
 
    /// Return from the logger manager singleton's category registry the
    /// address of the non-modifiable category having the specified
    /// `categoryName` if such a category exists, or if a new category
    /// having `categoryName` can be added to the registry (i.e., if the
    /// registry has sufficient capacity to accommodate new entries);
    /// otherwise, return the address of the non-modifiable *Default*
    /// *Category*.  Return 0 if the logger manager singleton is not
    /// initialized.
    static const Category *setCategory(const char *categoryName);
 
    /// Return the specified `categoryHolder` if the severity warrants
    /// logging according to the specified `t_SEVERITY` and
    /// `categoryHolder`, and 0 otherwise.
    template <int t_SEVERITY>
    static const CategoryHolder *categoryHolderIfEnabled(
                                         const CategoryHolder *categoryHolder);
 
    /// Load into the specified `categoryHolder` the address of the
    /// non-modifiable category having the specified `categoryName` if such
    /// a category exists, or if a new category having `categoryName` can
    /// be added to the registry (i.e., if the registry has sufficient
    /// capacity to accommodate new entries); otherwise, load the address of
    /// the non-modifiable *Default* *Category*.  Also load into
    /// `categoryHolder` the maximum threshold level of the category
    /// ultimately loaded into `categoryHolder`.  This method has no effect
    /// if the logger manager singleton is not initialized.
    static void setCategory(CategoryHolder *categoryHolder,
                            const char     *categoryName);
 
    /// Return from the logger manager singleton's category registry the
    /// address of the non-modifiable category having the specified
    /// `categoryName`, or, if no such category exists, add a new category
    /// having `categoryName` to the registry if possible (i.e., if the
    /// registry has sufficient capacity to accommodate new entries);
    /// otherwise, return the address of the non-modifiable *Default*
    /// *Category*.  If the logger manager singleton is not initialized,
    /// return 0 with no effect.  If a new category is created, it will have
    /// the same threshold levels as the category in the logger manager
    /// singleton whose name is the longest non-empty prefix of
    /// `categoryName` if such a category exists, and the threshold levels
    /// will be set as if `setCategory` had been called otherwise.
    static const Category *setCategoryHierarchically(const char *categoryName);
 
    /// Return from the logger manager singleton's category registry the
    /// address of the non-modifiable category having the specified
    /// `categoryName`, or, if no such category exists, add a new category
    /// having `categoryName` to the registry if possible (i.e., if the
    /// registry has sufficient capacity to accommodate new entries);
    /// otherwise, return the address of the non-modifiable *Default*
    /// *Category*.  If the logger manager singleton is not initialized,
    /// return 0 with no effect.  If a new category is created, it will have
    /// the same threshold levels as the category in the logger manager
    /// singleton whose name is the longest non-empty prefix of
    /// `categoryName` if such a category exists, and the threshold levels
    /// will be set as if `setCategory` had been called otherwise.  If the
    /// specified `categoryHolder` is non-zero, load it with the address of
    /// the returned category and the maximum threshold level of that
    /// category, and link `categoryHolder` to the other holders (if any) that currently reference the category.  
    /// 
    /// \note Note that   this method has
    /// the same effect on the logger manager singleton's category registry
    /// as the one-argument `setCategoryHierarchically` regardless of
    /// whether `0 == categoryHolder`.
    static const Category *setCategoryHierarchically(
                                                CategoryHolder *categoryHolder,
                                                const char     *categoryName);
 
    /// Return `true` if logging to the category associated with the
    /// specified `categoryHolder` at the specified `severity` is enabled,
    /// or if `Severity::e_WARN >= severity` and the logger manager
    /// singleton is not initialized; return `false` otherwise.
    static bool isCategoryEnabled(const CategoryHolder *categoryHolder,
                                  int                   severity);
};
 
                        // ================
                        // class Log_Stream
                        // ================
 
/// This class provides an aggregate of several objects relevant to the
/// logging of a message via the C++ stream-based macros:
/// @code
/// - record to be logged
/// - category to which to log the record
/// - severity at which to log the record
/// - stream to which the user log message is put
/// @endcode
/// As a side-effect of creating an object of this class, the record and
/// stream are also constructed.  As a side-effect of destroying the
/// object, the record is logged.
///
/// This class should *not* be used directly by client code.  It is an
/// implementation detail of the macros provided by this component.
///
/// See @ref ball_log 
class Log_Stream {
 
    // DATA
    const Category *d_category_p;  // category to which record is logged
                                   // (held, not owned)
 
    Record         *d_record_p;    // logged record (held, not owned)
 
    const int       d_severity;    // severity at which record is logged
 
  private:
    // NOT IMPLEMENTED
    Log_Stream(const Log_Stream&);
    Log_Stream& operator=(const Log_Stream&);
 
  public:
    // CREATORS
 
    /// Create a logging stream that holds (1) the specified `category` and
    /// `severity`, (2) a record that is created from the specified
    /// `fileName` and `lineNumber`, and (3) an `bsl::ostream` to which the
    /// log message is put.
    Log_Stream(const Category          *category,
               const bsl::string_view&  fileName,
               int                      lineNumber,
               int                      severity);
 
    /// Log the record held by this logging stream to the held category (as
    /// returned by `category`) at the held severity (as returned by
    /// `severity`) and destroy this logging stream.
    ~Log_Stream() BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(false);
 
    // MANIPULATORS
 
    /// Return the address of the modifiable log record held by this logging
    /// stream.  The address remains valid until this logging stream is
    /// destroyed.
    Record *record();
 
    /// Return a reference to the modifiable stream held by this logging
    /// stream.  The reference remains valid until this logging stream is
    /// destroyed.
    bsl::ostream& stream();
 
    // ACCESSORS
 
    /// Return the address of the non-modifiable category held by this
    /// logging stream.
    const Category *category() const;
 
    /// Return the address of the non-modifiable log record held by this
    /// logging stream.  The address remains valid until this logging stream
    /// is destroyed.
    const Record *record() const;
 
    /// Return the severity held by this logging stream.
    int severity() const;
};
 
                     // ===================
                     // class Log_Formatter
                     // ===================
 
/// This class provides an aggregate of several objects relevant to the
/// logging of a message via the `printf`-style macros:
/// @code
/// - record to be logged
/// - category to which to log the record
/// - severity at which to log the record
/// - buffer in which the user log message is formatted
/// @endcode
/// As a side-effect of creating an object of this class, the record is
/// constructed, and the buffer is obtained.  As a side-effect of destroying
/// the object, the record is formatted, using the buffer, and logged.
///
/// This class should *not* be used directly by client code.  It is an
/// implementation detail of the macros provided by this component.
///
/// See @ref ball_log 
class Log_Formatter {
 
    // DATA
    const Category          *d_category_p;  // category to which record is
                                            // logged (held, not owned)
 
    Record                  *d_record_p;    // logged record (held, not owned)
 
    const int                d_severity;    // severity at which record is
                                            // logged
 
    int                      d_bufferLen;   // length of buffer
 
    bslma::ManagedPtr<char>  d_buffer;      // buffer for formatted user log
                                            // message
 
  private:
    // NOT IMPLEMENTED
    Log_Formatter(const Log_Formatter&);
    Log_Formatter& operator=(const Log_Formatter&);
 
  public:
    // CREATORS
 
    /// Create a logging formatter that holds (1) the specified `category`
    /// and `severity`, (2) a record that is created from the specified
    /// `fileName` and `lineNumber`, and (3) a buffer into which the log
    /// message is formatted.
    Log_Formatter(const Category          *category,
                  const bsl::string_view&  fileName,
                  int                      lineNumber,
                  int                      severity);
 
    /// Log the record held by this logging formatter to the held category
    /// (as returned by `category`) at the held severity (as returned by
    /// `severity`), and destroy this logging formatter.
    ~Log_Formatter();
 
    // MANIPULATORS
 
    /// Return the address of the modifiable buffer held by this logging
    /// formatter.  The address remains valid until this logging formatter
    /// is destroyed.
    char *messageBuffer();
 
    /// Return the address of the modifiable log record held by this logging
    /// formatter.  The address remains valid until this logging formatter
    /// is destroyed.
    Record *record();
 
    // ACCESSORS
 
    /// Return the address of the non-modifiable category held by this
    /// logging formatter.
    const Category *category() const;
 
    /// Return the length (in bytes) of the buffer held by this logging
    /// formatter.
    int messageBufferLen() const;
 
    /// Return the address of the non-modifiable log record held by this
    /// logging formatter.  The address remains valid until this logging
    /// formatter is destroyed.
    const Record *record() const;
 
    /// Return the severity held by this logging formatter.
    int severity() const;
};
 
// ============================================================================
//                              INLINE DEFINITIONS
// ============================================================================
 
                                 // ----------
                                 // struct Log
                                 // ----------
 
// CLASS METHODS
template <int t_SEVERITY>
inline
const CategoryHolder *Log::categoryHolderIfEnabled(
                                          const CategoryHolder *categoryHolder)
{
    // The following condition is calculated at compile time so has no run-time
    // cost.  Code from the branch not taken will not be generated.  Note that
    // we expect TRACE and DEBUG messages not to be logged and thus they are
    // marked with unlikely performance hints.
 
    if (t_SEVERITY <= Severity::e_INFO) {
        if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(categoryHolder->threshold() >=
                                                t_SEVERITY)) {
            if (BSLS_PERFORMANCEHINT_PREDICT_LIKELY(
                         Log::isCategoryEnabled(categoryHolder, t_SEVERITY))) {
                return categoryHolder;                                // RETURN
            }
            else {
                BSLS_PERFORMANCEHINT_UNLIKELY_HINT;
            }
 
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;
        }
    }
    else {
        if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(
                                  categoryHolder->threshold() >= t_SEVERITY)) {
            BSLS_PERFORMANCEHINT_UNLIKELY_HINT;
 
            if (BSLS_PERFORMANCEHINT_PREDICT_UNLIKELY(
                         Log::isCategoryEnabled(categoryHolder, t_SEVERITY))) {
                BSLS_PERFORMANCEHINT_UNLIKELY_HINT;
 
                return categoryHolder;                                // RETURN
            }
        }
    }
 
    return 0;
}
 
inline
const Category *Log::setCategoryHierarchically(const char *categoryName)
{
    return setCategoryHierarchically(0, categoryName);
}
 
                             // ----------------
                             // class Log_Stream
                             // ----------------
 
// MANIPULATORS
inline
Record *Log_Stream::record()
{
    return d_record_p;
}
 
inline
bsl::ostream& Log_Stream::stream()
{
    return d_record_p->fixedFields().messageStream();
}
 
// ACCESSORS
inline
const Category *Log_Stream::category() const
{
    return d_category_p;
}
 
inline
const Record *Log_Stream::record() const
{
    return d_record_p;
}
 
inline
int Log_Stream::severity() const
{
    return d_severity;
}
 
                     // -------------------
                     // class Log_Formatter
                     // -------------------
 
// MANIPULATORS
inline
char *Log_Formatter::messageBuffer()
{
    return d_buffer.get();
}
 
inline
Record *Log_Formatter::record()
{
    return d_record_p;
}
 
// ACCESSORS
inline
const Category *Log_Formatter::category() const
{
    return d_category_p;
}
 
inline
int Log_Formatter::messageBufferLen() const
{
    return d_bufferLen;
}
 
inline
const Record *Log_Formatter::record() const
{
    return d_record_p;
}
 
inline
int Log_Formatter::severity() const
{
    return d_severity;
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2017 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */