ball_loggermanagerconfiguration

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a constrained-attribute class for the logger manager.

Classes

• ball::LoggerManagerConfiguration: configuration spec for a logger manager

See also

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

This section illustrates intended use of this component.

Example 1: Basic Usage

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
]