ball_severity

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Syntax
    • Example 2: Logging

Purpose

Enumerate a set of logging severity levels.

Classes

• ball::Severity: namespace for enumerating logging severity levels

Description

This component provides a namespace, ball::Severity, for the enum type ball::Severity::Level. Level enumerates a list of severity levels that can be attached to a logging event. In addition, this component supports functions that convert the Level enumerators to a well-defined ASCII representation.

Usage

This section illustrates intended use of this component.

Example 1: Syntax

The following snippets of code provide a simple illustration of ordinary ball::Severity operation. (The next example discusses a more elaborate usage scenario.)

First create a variable level of type ball::Severity::Level and initialize it to the value ball::Severity::e_ERROR.

    ball::Severity::Level level = ball::Severity::e_ERROR;

Next, store a pointer to its ASCII representation in a variable asciiLevel of type const char *.

    const char *asciiLevel = ball::Severity::toAscii(level);
    assert(0 == strcmp(asciiLevel, "ERROR"));

Finally, print the value of level to bsl::cout.

    bsl::cout << level << bsl::endl;

This statement produces the following output on stdout:

    ERROR

Example 2: Logging

Consider a general-purpose logging facility that provides two interfaces: one for developers to use when logging from subroutines and another to be used by the owner of the main program to administer how much information is to be published to a log file. Messages logged with numeric values at or below the globally-administered threshold level are published to the log, while those logged with higher (less severe) levels are not. Being general-purpose, we envision that additional levels may be useful in some applications. Hence, the numeric values supplied in this component might be augmented with additional severity levels. For example:

    enum {
        MAJOR_ERROR =  48
        MINOR_ERROR =  80,
        DEBUG2      = 162
    };

Given that library modules using augmented logging schemes may coexist in a single program, we would choose not to have the core logging facility depend on this enumeration, but instead accept integer log levels in the range [0 .. 255]. Hence, those that choose to limit their logging levels to the seven defined in ball::Severity can do so, and still coexist on the same logging facility along side routines that log with more finely-graduated levels of severity.

To facilitate administration, the following enumerated values, in addition to any level values supplied to programmers, should be available to the owner of the main program to control output:

    enum {
        ALL = 255,  // publish all log messages
        OFF =  -1   // disable logging
    };

Setting the global threshold to ALL causes all messages to be published; setting it to OFF disables logging.