Component ball_loggermanagerdefaults [Package ball]

Provide constrained default attributes for the logger manager. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Design Note
  • Usage

Purpose:

Provide constrained default attributes for the logger manager.

Classes:

ball::LoggerManagerDefaults

default parameters for logger manager

See also:

Component ball_loggermanagerconfiguration

Description:

This component provides a simply-constrained attribute class, ball::LoggerManagerDefaults, 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 contained by a ball::LoggerManagerDefaults object and the attribute constraints are given, respectively, in two tables below. The attributes are as follows:

   TYPE          NAME                DESCRIPTION
   -----------   ----------------    -------------------------------------
   int           recordBufferSize    size in bytes of *default* logger's
                                     record buffer
   int           loggerBufferSize    default size in bytes of *each*
                                     logger's "scratch" buffer (for macros)
   char          recordLevel         default record severity level
   char          passLevel           default pass-through severity level
   char          triggerLevel        default trigger severity level
   char          triggerAllLevel     default triggerAll severity level

The constraints are as follows:

    NAME                 CONSTRAINT
   +--------------------+---------------------------------------------+
   | recordBufferSize   | 1 <= recordBufferSize                       |
   +--------------------+---------------------------------------------+
   | loggerBufferSize   | 1 <= loggerBufferSize                       |
   +--------------------+---------------------------------------------+
   | recordLevel        | 0 <= recordLevel     <= 255                 |
   | passLevel          | 0 <= passLevel       <= 255                 |
   | triggerLevel       | 0 <= triggerLevel    <= 255                 |
   | triggerAllLevel    | 0 <= triggerAllLevel <= 255                 |
   +--------------------+---------------------------------------------+

Although the numerical constraints on the four severity levels are independent of one another, they are treated as logically coupled, and must be set as a group. If any one value cannot be successfully set, then the whole set operation fails with no effect on the object value. This may be viewed as an auxiliary constraint.

Thread Safety:

This constrained-attribute component is thread-safe but not thread-enabled, and requires explicit synchronization in the user space.

Design Note:

This component provides a BDE constrained-attribute type designed to be useful to ball::LoggerManager. However, ball::LoggerManagerDefaults is not ball::LoggerManagerConfiguration, the actual configuration object used by the logger manager. ball::LoggerManagerConfiguration is not a value semantic type, because it holds functors. ball::LoggerManagerDefaults, which is used by ball::LoggerManagerConfiguration, may be regarded as a factored detail of the actual configuration object.

Usage:

The following snippets of code illustrate how to use a ball::LoggerManagerDefaults object. First, create a configuration object lmd. Note that it is necessarily configured to valid but unpublished defaults.

    ball::LoggerManagerDefaults lmd;

Next, set each attribute. Note that the four severity threshold levels must be set atomically (i.e., with a single four-argument "set" method). Note also that each "set" method will fail if the argument or set of arguments is not valid, and so each method returns a status value.

    assert(    0 == lmd.setDefaultRecordBufferSizeIfValid(32768));
    assert(32768 == lmd.defaultRecordBufferSize());

    assert(   0 == lmd.setDefaultLoggerBufferSizeIfValid(2048));
    assert(2048 == lmd.defaultLoggerBufferSize());

    assert(  0 == lmd.setDefaultThresholdLevelsIfValid(192, 64, 48, 32));
    assert(192 == lmd.defaultRecordLevel());
    assert( 64 == lmd.defaultPassLevel());
    assert( 48 == lmd.defaultTriggerLevel());
    assert( 32 == lmd.defaultTriggerAllLevel());

The configuration object is now validly configured with our choice of parameters. If, however, we attempt to set an invalid configuration, the "set" method will fail (with a non-zero return status), and the configuration will be left unchanged.

    assert(  0 != lmd.setDefaultThresholdLevelsIfValid(256, 90, 60, 30));
    assert(192 == lmd.defaultRecordLevel());
    assert( 64 == lmd.defaultPassLevel());
    assert( 48 == lmd.defaultTriggerLevel());
    assert( 32 == lmd.defaultTriggerAllLevel());

Finally, we can print the configuration value to stdout.

    bsl::cout << lmd << bsl::endl;

This produces the following (multi-line) output:

 [
     recordBufferSize : 32768
     loggerBufferSize : 2048
     recordLevel      : 192
     passLevel        : 64
     triggerLevel     : 48
     triggerAllLevel  : 32
 ]