Macros
#define	BSLS_LOG(severity, ...)

#define	BSLS_LOG_FATAL(...)

#define	BSLS_LOG_ERROR(...)

#define	BSLS_LOG_WARN(...)

#define	BSLS_LOG_INFO(...)

#define	BSLS_LOG_DEBUG(...)

#define	BSLS_LOG_TRACE(...)

#define	BSLS_LOG_SIMPLE(severity, msg) (BloombergLP::bsls::Log::logMessage((severity), __FILE__, __LINE__, (msg)))

Detailed Description

Outline

Purpose
Classes
Macros
Description

Purpose

Provide a namespace for low-level logging functions.

Classes

bsls::Log: namespace for low-level logging functions

Macros

BSLS_LOG: write log message using printf-style format specification
BSLS_LOG_SIMPLE: write log message as an unformatted string
BSLS_LOG_FATAL: write fatal message using printf format specification
BSLS_LOG_ERROR: write error message using printf format specification
BSLS_LOG_WARN: write warning message using printf format specification
BSLS_LOG_INFO: write info message using printf format specification
BSLS_LOG_DEBUG: write debug message using printf format specification
BSLS_LOG_TRACE: write trace message using printf format specification

See also: bsls_logseverity

Description

This component provides a set of macros, along with a namespace, bsls::Log, which contains a suite of utility functions for logging in low-level code. The macros and functions in this component provide a consistent interface for logging across different platforms through the use of a global cross-platform log message handler function. Users can customize the logging behavior by providing their own log message handler function. Note that this component is intended to be used only when a more fully-featured logger is not available.

Macro Reference

This section provides documentation for the macros defined in this component.

BSLS_LOG(severity, ...)
   If the specified 'severity' is at least as severe as
   'Log::severityThreshold', write a message having 'severity' to the
   currently installed log message handler, which contains a formatted
   string that would result from applying the 'printf'-style formatting
   rules to the specified '...', using the first parameter as the format
   string and any further parameters as the expected substitutions.  If
   'severity' is less severe than 'severityThreshold' then this macro has
   no effect.  The file name and line number of the point of expansion of
   the macro are automatically used as the file name and line number for
   the log message.  The behavior is undefined unless the first parameter
   of '...' is a valid 'printf'-style format string, and all substitutions
   needed by the format string are in the subsequent elements of '...'.
 
BSLS_LOG_FATAL(...)
BSLS_LOG_ERROR(...)
BSLS_LOG_WARN(...)
BSLS_LOG_INFO(...)
BSLS_LOG_DEBUG(...)
BSLS_LOG_TRACE(...)
   Instantiate the 'BSLS_LOG' macro with the severity appropriate for
   the macros name.  Note that this is syntactic sugar, to avoid the
   complete text "bsls::LogSeverity::e_" being needed each time a message
   is logged with 'BSLS_LOG'.
 
BSLS_LOG_SIMPLE(severity, msg)
   If the specified 'severity' is at least as severe as
   'Log::severityThreshold', write a message having 'severity' and the
   specified 'msg' to the currently installed log message handler, with the
   file name and line number of the point of expansion of the macro
   automatically used as the file name and line number of the log.  If
   'severity' is less severe than 'severityThreshold' then this macro has
   no effect.

Motivation

Using the functionality of this component instead of writing messages directly to stderr has the following advantages:

Users have the freedom to customize the default logging behavior. A user may want all logs to be automatically redirected to a file or may want to add some custom formatting or handling. These abilities are not available if the output stream is predetermined.
The logging mechanism behaves correctly on all platforms by default. Some platforms have particular restrictions on the use of the standard output streams. For example, Windows applications running in non-console mode do not have a concept of stdout or stderr; writing directly to either of these streams is known to hang the process when no console is attached.

Functionality

This section describes the functionality provided by this component in more detail.

Log Message Handler

The bsls::Log class provides two static methods, logMessageHandler and setLogMessageHandler, which can be used, respectively, to retrieve and set the globally installed log message handler through which all log messages are written. All log message handlers must follow the signature and contract requirements of the bsls::Log::LogMessageHandler typedef.

The log message handler bsls::Log::platformDefaultMessageHandler is installed by default as the global handler. This handler writes all log messages to stderr, except in Windows non-console mode where the destination of the OutputDebugString function is used.

In addition to the default handler, the log message handlers bsls::Log::stdoutMessageHandler and bsls::Log::stderrMessageHandler are provided as a set of simple handlers that write log messages to stdout and stderr, respectively.

Writing Log Messages

There are four ways to invoke the currently installed log message handler, depending on the specific behavior required: The macro BSLS_LOG allows a formatted message to be written using a printf-style format string. The macro BSLS_LOG_SIMPLE allows a simple, unformatted string to be written. Both of the macros automatically use the file name and line number of the point that the macro was invoked. The static methods bsls::Log::logFormattedMessage and bsls::Log::logMessage provide the same functionality as BSLS_LOG and 'BSLS_LOG_SIMPLE, respectively, except that these two methods allow a file name and line number to be passed in as parameters. This is described in table form as follows:

.=========================================================================.
|      Mechanism                 |  Formatted   |  Automatic File & Line  |
|=========================================================================|
| BSLS_LOG                       |     YES      |          YES            |
|--------------------------------|--------------|-------------------------|
| BSLS_LOG_[LEVEL]               |     YES      |          YES            |
|--------------------------------|--------------|-------------------------|
| BSLS_LOG_SIMPLE                |     NO       |          YES            |
|--------------------------------|--------------|-------------------------|
| bsls::Log::logFormattedMessage |     YES      |          NO             |
|--------------------------------|--------------|-------------------------|
| bsls::Log::logMessage          |     NO       |          NO             |
`-------------------------------------------------------------------------'

Log Severity and the Severity Threshold

Clients submitting a message to bsls::Log (either through a function or one of the macros) either implicitly or explicitly provide a severity level describing the relative importance of that message to clients. The possible severity levels are FATAL, ERROR, WARNING, INFO, DEBUG, and TRACE (these are enumerated in bsls_logseverity ).

The severity of a logged message is used to determine whether the message is published to the log using the currently installed LogMessageHandler callback. Also, typically a LogMessageHandler callback implementation will report a message's severity along side that message in the log.

Clients can configure the severity threshold, at or above which a log message will be published, using setSeverityThreshold. For example:

// Messages having 'e_WARN' or higher severity will be output to the log.
 
bsls::Log::setSeverityThreshold(bsls::LogSeverity::e_WARN);

Usage

This section illustrates the intended use of this component.

Example 1: Logging Formatted Messages

Suppose that we want to write a formatted log message using printf-style format specifiers when the preconditions of a function are not met. The BSLS_LOG macro can be used for this purpose.

First, we begin to define a function, add, which will return the sum of two positive integer values:

// myapp.cpp
 
unsigned int add(int a, int b)
    // Return the sum of the specified 'a' and the specified 'b'.  The
    // behavior is undefined unless 'a' and 'b' are not negative.
{

Now, we check the precondition of the function, and use the BSLS_LOG_ERROR macro to write a log message if one of the input parameters is less than 0:

    if(a < 0 || b < 0) {
        BSLS_LOG_ERROR("Invalid input combination (%d, %d).", a, b);
        return 0;                                                 // RETURN
    }
 
    return static_cast<unsigned int>(a) + static_cast<unsigned int>(b);
}

Next, we may erroneously call the add function with a negative argument:

unsigned int x = add(3, -100);

Finally, assuming the default log message handler is currently installed, we observe the following output printed to stderr or to the Windows debugger:

ERROR myapp.cpp:8 Invalid input combination (3, -100).

Note that an arbitrary string should never be passed to BSLS_LOG as the format string. If the string happens to contain printf-style format specifiers but the expected substitutions are not present, it will lead to undefined behavior.

Macro Definition Documentation

◆ BSLS_LOG

#define BSLS_LOG	(	severity,
		...
	)

Value:

  do {                                                                        \
    if (severity <= BloombergLP::bsls::Log::severityThreshold()) {            \
      BloombergLP::bsls::Log::logFormattedMessage((severity),                 \
                                                  __FILE__,                   \
                                                  __LINE__,                   \
                                                  __VA_ARGS__);               \
    }                                                                         \
  } while(false)

◆ BSLS_LOG_DEBUG

#define BSLS_LOG_DEBUG ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_DEBUG,\

__VA_ARGS__)

◆ BSLS_LOG_ERROR

#define BSLS_LOG_ERROR ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_ERROR,\

__VA_ARGS__)

◆ BSLS_LOG_FATAL

#define BSLS_LOG_FATAL ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_FATAL,\

__VA_ARGS__)

◆ BSLS_LOG_INFO

#define BSLS_LOG_INFO ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_INFO, \

__VA_ARGS__)

◆ BSLS_LOG_SIMPLE

#define BSLS_LOG_SIMPLE	(	severity,
		msg
	)	(BloombergLP::bsls::Log::logMessage((severity), __FILE__, __LINE__, (msg)))

◆ BSLS_LOG_TRACE

#define BSLS_LOG_TRACE ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_TRACE,\

__VA_ARGS__)

◆ BSLS_LOG_WARN

#define BSLS_LOG_WARN ( ... )

Value:

BSLS_LOG(BloombergLP::bsls::LogSeverity::e_WARN, \

__VA_ARGS__)