Component ball_category [Package ball]

Provide a container for a name and associated thresholds. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • ball "Private" Methods and Classes
    • ball::CategoryHolder
    • ball::CategoryManagerImpUtil
  • Usage
    • Example 1: Basic Use of ball::Category

Purpose:

Provide a container for a name and associated thresholds.

Classes:

ball::Category	container for a name and associated threshold levels
ball::CategoryHolder	private holder of a category and its maximum level
ball::CategoryManagerImpUtil	private used in creating a category manager

See also:

Component ball_categorymanager

Description:

This component primarily provides a class, ball::Category, used to describe the properties of a logging category. A ball::Category provides access to the category name and the 4 logging threshold levels associated with a category (see ball_loggermanager for a description of the purpose of the various thresholds).

ball "Private" Methods and Classes:

This component provides classes that are not intended for use by the users of the ball logging sub-system: ball::CategoryHolder and ball::CategoryManagerImpUtil. These classes are defined in this component because they are either friends of ball::Category or have a circular definition with ball::Category. They are used within the logging sub-system to efficiently process log records.

ball::CategoryHolder:

A ball::CategoryHolder is a statically-initializable pointer to a log category. It is designed to work with the logging macros provided by ball (see ball_log), and provide a static cache of the log category at the point where a log macro is invoked.

ball::CategoryManagerImpUtil:

A ball::CategoryManagerImpUtil provides a suite of utility functions used in creating a manager for log categories (see ball_categorymanager). A ball::Category object maintains private state that is accessed and manipulated via this utility. Each ball::Category contains private data members that provide:

• A linked list of associated ball::CategoryHolder objects that refer to the category.
• A cache of the logging rules that apply to the category.
• A cache of the maximum threshold associated with any rule that applies to the category (this is the threshold at which a more complicated evaluation of the logging rules and current ball::AttributeContext must be performed).

Usage:

This section illustrates intended use of this component.

Example 1: Basic Use of ball::Category:

The following example demonstrates creating a category and accessing its threshold information.

Note that other components in the logging subsystem provide more user focused examples of using categories (see ball_loggermanager, ball_administration, and ball_categorymanager).

First we create a simple category, example, that has the record-level, trigger-level, and trigger-all thresholds set to OFF and the pass-level set to WARN, and verify these values:

  ball::Category example("example",
                         ball::Severity::e_OFF,
                         ball::Severity::e_WARN,
                         ball::Severity::e_OFF,
                         ball::Severity::e_OFF);

  assert(0 == bsl::strcmp("example", example.categoryName());
  assert(ball::Severity::e_OFF  == example.recordLevel());
  assert(ball::Severity::e_WARN == example.passLevel());
  assert(ball::Severity::e_OFF  == example.triggerLevel());
  assert(ball::Severity::e_OFF  == example.triggerAllLevel());

See ball_loggermanager for more information on the use of various thresholds levels.

Finally, we test if a the category is enabled for log record recorded with e_ERROR severity:

  if (example.isEnabled(ball::Severity::e_ERROR)) {
      // publish record
  }