Component ball_loggermanagerconfiguration [Package ball]

Provide a constrained-attribute class for the logger manager. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage

Purpose:

Provide a constrained-attribute class for the logger manager.

Classes:

ball::LoggerManagerConfiguration

configuration spec for a logger manager

See also:

Component ball_loggermanagerdefaults

Description:

This component provides a constrained-attribute class that contains a set of attributes (objects and parameters) of particular use to logger managers. The constraints are actively maintained by the class. In particular, the "set" methods for constrained values will fail if their arguments are not consistent with the constraints. Also, the constructor does not take any constrained arguments, but rather sets those values to valid defaults unconditionally. This behavior avoids "silent failures", since the constructor cannot explicitly return a status value.

The attributes of a ball::LoggerManagerConfiguration object and their constraints are given, respectively, in two tables below. Before listing the attributes, however, we list the types that are provided by the ball::LoggerManagerConfiguration class to simply the definition of some of the attributes:

  TYPE                                         'typedef' alias
  ------------------------------------------   ------------------------------
  bsl::function<void(ball::UserFields *)>      UserFieldsPopulatorCallback

  bsl::function<void(bsl::string *, const char *)>
                                               CategoryNameFilterCallback

  bsl::function<void(int *, int *, int *, int *, const char *)>
                                               DefaultThresholdLevelsCallback

The attributes contained by a ball::LoggerManagerConfiguration object follow:

  TYPE                                         NAME
  ------------------------------------------   ------------------------------
  ball::LoggerManagerDefaults                  defaults

  UserFieldsPopulatorCallback                  userFieldsPopulatorCallback

  CategoryNameFilterCallback                   categoryNameFilterCallback

  DefaultThresholdLevelsCallback               defaultThresholdLevelsCallback

  LogOrder                                     logOrder

  TriggerMarkers                               triggerMarkers

  NAME                            DESCRIPTION
  -------------------             -------------------------------------------
  defaults                        constrained defaults for buffer size and
                                  thresholds

  userFieldsPopulatorCallback     populates user-defined fields in a log
                                  record

  categoryNameFilterCallback      invoked on category names, e.g., to re-map
                                  characters

  defaultThresholdLevelsCallback  sets category severity threshold levels (by
                                  default)

  logOrder                        defines the order in which log messages are
                                  published for Trigger and Trigger-All
                                  events; default is LIFO (last-in first-out)

  triggerMarkers                  defines whether text will be written to the
                                  log to indicate whether a series of log
                                  records were logged due to either a Trigger
                                  or Trigger-All event; if this attribute is
                                  'e_BEGIN_END_MARKERS', then
                                  "BEGIN RECORD DUMP" and "END RECORD DUMP"
                                  will be written before and after each
                                  sequence of records logged due to a Trigger
                                  or Trigger-All event; default is
                                  'e_BEGIN_END_MARKERS'.

The constraints are as follows:

    NAME                             CONSTRAINT
  +--------------------------------+--------------------------------+
  | defaults                       | (a constrained-attribute type) |
  +--------------------------------+--------------------------------+
  | userFieldsPopulatorCallback    | (none)                         |
  +--------------------------------+--------------------------------+
  | categoryNameFilterCallback     | (none)                         |
  +--------------------------------+--------------------------------+
  | defaultThresholdLevelsCallback | (none)                         |
  +--------------------------------+--------------------------------+
  | logOrder                       | (none)                         |
  +--------------------------------+--------------------------------+
  | triggerMarkers                 | (none)                         |
  +--------------------------------+--------------------------------+

For convenience, the ball::LoggerManagerConfiguration interface contains manipulators and accessors to configure and inspect the value of its contained ball::LoggerManagerDefaults object; these methods are identical to those of ball::LoggerManagerDefaults. See the ball_loggermanagerdefaults component for details on the defaults and their constraints.

Thread Safety:

This constrained-attribute component is thread-safe but not thread-enabled, and requires explicit synchronization in the user space. Note that any of the contained user-defined callbacks may be invoked from any thread, and the user must account for that.

Usage:

The following snippets of code illustrate how to use a ball::LoggerManagerConfiguration object.

First, we define a simple function that will serve as a UserFieldsPopulatorCallback, a callback that will be invoked for each logged message to populate user defined fields for the log record:

  void exampleCallback(ball::UserFields *fields)
  {
      fields->appendString("example user field value");
  }

Next, we define a function inititialize in which we will create and configure a ball::LoggerManagerConfiguration object (see ball_loggermanager for an example of how to create the logger-manager singleton object):

  void initializeConfiguration(bool verbose)
  {
    ball::LoggerManagerConfiguration config;

Then, we configure the default record buffer size, logger buffer size, and the various logging thresholds (see ball_loggermanager for more information on the various threshold levels):

    if (0 != config.setDefaultRecordBufferSizeIfValid(32768) ||
        0 != config.setDefaultLoggerBufferSizeIfValid(1024)  ||
        0 != config.setDefaultThresholdLevelsIfValid(0, 64, 0, 0)) {
       bsl::cerr << "Failed set log configuration defaults." << bsl::endl;
       bsl::exit(-1);
    }

    assert(32768 == config.defaultRecordBufferSize());
    assert( 1024 == config.defaultLoggerBufferSize());
    assert(    0 == config.defaultRecordLevel());
    assert(   64 == config.defaultPassLevel());
    assert(    0 == config.defaultTriggerLevel());
    assert(    0 == config.defaultTriggerAllLevel());

Next, we populate the remaining attributes of our configuration object (note that the following methods cannot fail and return void):

    config.setUserFieldsPopulatorCallback(&exampleCallback);
    config.setLogOrder(ball::LoggerManagerConfiguration::e_FIFO);
    config.setTriggerMarkers(ball::LoggerManagerConfiguration::e_NO_MARKERS);

Now, we verify the options are configured correctly:

    assert(ball::LoggerManagerConfiguration::e_FIFO == config.logOrder());
    assert(ball::LoggerManagerConfiguration::e_NO_MARKERS
                                                 == config.triggerMarkers());

Finally, we print the configuration value to stdout and return:

    if (verbose) {
      bsl::cout << config << bsl::endl;
    }
  }

This produces the following (multi-line) output:

  [
      Defaults:
      [
          recordBufferSize : 32768
          loggerBufferSize : 1024
          recordLevel      : 0
          passLevel        : 64
          triggerLevel     : 0
          triggerAllLevel  : 0
      ]
      User Fields Populator functor is not null
      Category Name Filter functor is null
      Default Threshold Callback functor is null
      Logging order is FIFO
      Trigger markers are NO_MARKERS
  ]