ball_category

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

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
}