# Logging sources

Andrey Semashev

08.03.2007

The header contains implementation of a base class for loggers. Convenience macros for defining custom loggers are also provided. Basic logger class.

The ``basic_logger`` class template serves as a base class for all loggers provided by the library. It can also be used as a base for user-defined loggers. The template parameters are:

- `CharT` - logging character type

- `FinalT` - final type of the logger that eventually derives from the ``basic_logger``. There may be other classes in the hierarchy between the final class and ``basic_logger``.

- `ThreadingModelT` - threading model policy. Must provide methods of the Boost.Thread locking concept used in ``basic_logger`` class and all its derivatives in the hierarchy up to the `FinalT` class. The ``basic_logger`` class itself requires methods of the SharedLockable concept. The threading model policy must also be default and copy-constructible and support member function `swap`. There are currently two policies provided: ``single_thread_model`` and ``multi_thread_model``.

The logger implements fundamental facilities of loggers, such as storing source-specific attribute set and formatting log record messages. The basic logger interacts with the logging core in order to apply filtering and pass records to sinks. Character type. CharT Final logger type. FinalT Threading model type. ThreadingModelT Lock requirement for the swap_unlocked method. unspecified Lock requirement for the add_attribute_unlocked method. unspecified Lock requirement for the remove_attribute_unlocked method. unspecified Lock requirement for the remove_all_attributes_unlocked method. unspecified Lock requirement for the get_attributes method. unspecified Lock requirement for the open_record_unlocked method. unspecified Lock requirement for the set_attributes method. unspecified Lock requirement for the push_record_unlocked method. no_lock< threading_model >

Constructor. Initializes internal data structures of the basic logger class, acquires reference to the logging core.

``basic_logger` const &

Source logger

`

Copy constructor. Copies all attributes from the source logger.

Not thread-safe. The source logger must be locked in the final class before copying.

``basic_logger` &&

Source logger

`

Move constructor. Moves all attributes from the source logger.

Not thread-safe. The source logger must be locked in the final class before copying.

`ArgsT const &`

Constructor with named arguments. The constructor ignores all arguments. The result of construction is equivalent to default construction.

core_ptr const &

An accessor to the logging system pointer

attribute_set &

An accessor to the logger attributes

attribute_set const &

An accessor to the logger attributes

threading_model &

An accessor to the threading model base

threading_model const &

An accessor to the threading model base

final_type *

An accessor to the final logger

final_type const *

An accessor to the final logger

void``basic_logger` &`

Unlocked `swap`

std::pair< attribute_set::iterator, bool >`attribute_name const &``attribute const &`

Unlocked `add_attribute`

void `attribute_set::iterator`

Unlocked `remove_attribute`

void

Unlocked `remove_all_attributes`

record

Unlocked `open_record`

record `ArgsT const &`

Unlocked `open_record`

void `record &&`

Unlocked `push_record`

attribute_set

Unlocked `get_attributes`

void `attribute_set const &`

Unlocked `set_attributes`

`basic_logger` &``basic_logger` const &`Assignment is closed (should be implemented through copy and swap in the final class) A composite logger that inherits a number of features.

The composite logger is a helper class that simplifies feature composition into the final logger. The user's logger class is expected to derive from the composite logger class, instantiated with the character type, the user's logger class, the threading model and the list of the required features. The former three parameters are passed to the ``basic_logger`` class template. The feature list must be an MPL type sequence, where each element is a unary MPL metafunction class, that upon applying on its argument results in a logging feature class that derives from the argument. Every logger feature provided by the library can participate in the feature list.

Threading model being used. base_type::threading_model std::pair< attribute_set::iterator, bool >`attribute_name const &

The attribute name.

``attribute const &

The attribute factory.

`

The method adds an attribute to the source-specific attribute set. The attribute will be implicitly added to every log record made with the current logger.

A pair of values. If the second member is `true`, then the attribute is added and the first member points to the attribute. Otherwise the attribute was not added and the first member points to the attribute that prevents addition.

void `attribute_set::iterator

Iterator to the previously added attribute.

`

The method removes an attribute from the source-specific attribute set.

The attribute was added with the add_attribute call for this instance of the logger.

The attribute is no longer registered as a source-specific attribute for this logger. The iterator is invalidated after removal.

void

The method removes all attributes from the logger. All iterators and references to the removed attributes are invalidated.

attribute_set

The method retrieves a copy of a set with all attributes from the logger.

The copy of the attribute set. Attributes are shallow-copied.

void `attribute_set const &

The set of attributes to install into the logger. Attributes are shallow-copied.

`

The method installs the whole attribute set into the logger. All iterators and references to elements of the previous set are invalidated. Iterators to the attrs set are not valid to be used with the logger (that is, the logger owns a copy of attrs after completion).

record

The method opens a new log record in the logging core.

A valid record handle if the logging record is opened successfully, an invalid handle otherwise.

record `ArgsT const &

A set of additional named arguments. The parameter is ignored.

`

The method opens a new log record in the logging core.

A valid record handle if the logging record is opened successfully, an invalid handle otherwise.

void `record &&

The log record with the formatted message

`

The method pushes the constructed message to the logging core

void``basic_composite_logger` &`

Thread-safe implementation of swap

Default constructor (default-constructs all features)

``basic_composite_logger` const &`

Copy constructor

`logger_base &&`

Move constructor

`ArgsT const &`

Constructor with named parameters

FinalT &`FinalT const &`

Assignment for the final class. Threadsafe, provides strong exception guarantee.

CharTFinalTsingle_thread_modelFeaturesT An optimized composite logger version with no multithreading support. base_type::threading_model std::pair< attribute_set::iterator, bool >`attribute_name const &``attribute const &` void `attribute_set::iterator` void attribute_set void `attribute_set const &` record record `ArgsT const &` void `record &&` void``basic_composite_logger` &` ``basic_composite_logger` const &` ``logger_base` &&` `ArgsT const &` FinalT &`FinalT` `void ``basic_logger`< CharT, FinalT, ThreadingModelT > &```basic_logger`< CharT, FinalT, ThreadingModelT > &`

Free-standing swap for all loggers

`

The name of the logger class to declare

The character type of the logger. Either char or wchar_t expected.

A Boost.Preprocessor sequence of type identifiers of the base classes templates

A threading model class

The macro declares a logger class that inherits a number of base classes.

The name of the logger class to declare

A Boost.Preprocessor sequence of type identifiers of the base classes templates

The macro declares a narrow-char logger class that inherits a number of base classes.

Equivalent to BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq, single_thread_model)

The name of the logger class to declare

A Boost.Preprocessor sequence of type identifiers of the base classes templates

The macro declares a narrow-char thread-safe logger class that inherits a number of base classes.

Equivalent to `BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, char, base_seq, multi_thread_model< shared_mutex >)`

The name of the logger class to declare

A Boost.Preprocessor sequence of type identifiers of the base classes templates

The macro declares a wide-char logger class that inherits a number of base classes.

Equivalent to BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq, single_thread_model)

The name of the logger class to declare

A Boost.Preprocessor sequence of type identifiers of the base classes templates

The macro declares a wide-char thread-safe logger class that inherits a number of base classes.

Equivalent to `BOOST_LOG_DECLARE_LOGGER_TYPE(type_name, wchar_t, base_seq, multi_thread_model< shared_mutex >)`

Andrey Semashev

28.02.2008

The header contains implementation of a channel support feature. Channel feature implementation. Default channel name generator. channel_type result_type Character type. base_type::char_type Final type. base_type::final_type Threading model being used. base_type::threading_model Channel type. ChannelT Channel attribute type. attributes::mutable_constant< channel_type > Lock requirement for the `open_record_unlocked` method. unspecified Lock requirement for the `swap_unlocked` method. unspecified channel_type

The observer of the channel name

The channel name that was set by the logger

void `channel_type const &

The channel name to be set for the logger

`

The setter of the channel name

Default constructor. The constructed logger has the default-constructed channel name.

``basic_channel_logger` const &`

Copy constructor

``basic_channel_logger` &&`

Move constructor

`ArgsT const &

A set of named arguments. The following arguments are supported:

- `channel` - a string that represents the channel name

`

Constructor with arguments. Allows to register a channel name attribute on construction.

channel_attribute const &

Channel attribute accessor

record `ArgsT const &`

Unlocked `open_record`

void``basic_channel_logger` &`

Unlocked swap

record `ArgsT const &``T const &`The `open_record` implementation for the case when the channel is specified in log statement. record `ArgsT const &``parameter::void_`The `open_record` implementation for the case when the channel is not specified in log statement. std::string Channel support feature.

The logger with this feature automatically registers an attribute with the specified on construction value, which is a channel name. The channel name can be modified through the logger life time, either by calling the `channel` method or by specifying the name in the logging statement.

The type of the channel name can be customized by providing it as a template parameter to the feature template. By default, a string will be used.

`basic_channel_logger`< BaseT, ChannelT > The macro allows to put a record with a specific channel name into log. An equivalent to BOOST_LOG_STREAM_CHANNEL(logger, chan)

Andrey Semashev

28.02.2008

The header contains implementation of a logger with channel support. std::string basic_composite_logger< char, channel_logger< ChannelT >, single_thread_model, features< channel< ChannelT > > >Narrow-char logger. Functionally equivalent to ``basic_channel_logger``.

See `channel` class template for a more detailed description

Default constructor

``channel_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`ChannelT const &

The channel name

`

The constructor creates the logger with the specified channel name

`channel_logger` &``channel_logger` const &`

Assignment operator

Swaps two loggers

std::string basic_composite_logger< char, channel_logger_mt< ChannelT >, multi_thread_model< implementation_defined >, features< channel< ChannelT > > >Narrow-char thread-safe logger. Functionally equivalent to ``basic_channel_logger``.

See `channel` class template for a more detailed description

Default constructor

``channel_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`ChannelT const &

The channel name

`

The constructor creates the logger with the specified channel name

`channel_logger_mt` &``channel_logger_mt` const &`

Assignment operator

Swaps two loggers

std::wstring basic_composite_logger< wchar_t, wchannel_logger< ChannelT >, single_thread_model, features< channel< ChannelT > > >Wide-char logger. Functionally equivalent to ``basic_channel_logger``.

See `channel` class template for a more detailed description

Default constructor

``wchannel_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`ChannelT const &

The channel name

`

The constructor creates the logger with the specified channel name

`wchannel_logger` &``wchannel_logger` const &`

Assignment operator

Swaps two loggers

std::wstring basic_composite_logger< wchar_t, wchannel_logger< ChannelT >, multi_thread_model< implementation_defined >, features< channel< ChannelT > > >Wide-char thread-safe logger. Functionally equivalent to ``basic_channel_logger``.

See `channel` class template for a more detailed description

Default constructor

``wchannel_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`ChannelT const &

The channel name

`

The constructor creates the logger with the specified channel name

`wchannel_logger_mt` &``wchannel_logger_mt` const &`

Assignment operator

Swaps two loggers

Andrey Semashev

17.07.2009

The header contains implementation of an exception handler support feature. Exception handler feature implementation. Threading model being used. base_type::threading_model Final logger type. base_type::final_type Exception handler function type. unspecified Lock requirement for the open_record_unlocked method. strictest_lock< typename base_type::open_record_lock, no_lock< threading_model > >::type Lock requirement for the push_record_unlocked method. strictest_lock< typename base_type::push_record_lock, no_lock< threading_model > >::type Lock requirement for the swap_unlocked method. unspecified void `HandlerT const &

Exception handling function

`

The method sets exception handler function. The function will be called with no arguments in case if an exception occurs during either `open_record` or `push_record` method execution. Since exception handler is called from a `catch` statement, the exception can be rethrown in order to determine its type.

By default no handler is installed, thus any exception is propagated as usual.

See Also:

`utility/exception_handler.hpp`

The exception handler can be invoked in several threads concurrently.

Thread interruptions are not affected by exception handlers.

Default constructor. The constructed logger does not have an exception handler.

``basic_exception_handler_logger` const &`

Copy constructor

``basic_exception_handler_logger` &&`

Move constructor

`ArgsT const &`

Constructor with arguments. Passes arguments to other features.

record `ArgsT const &`

Unlocked `open_record`

void `record &&`

Unlocked `push_record`

void``basic_exception_handler_logger` &`

Unlocked swap

Exception handler support feature.

The logger with this feature will provide an additional method to install an exception handler functional object. This functional object will be called if during either opening or pushing a record an exception is thrown from the logging core.

`basic_exception_handler_logger`< BaseT >

Andrey Semashev

17.07.2009

The header contains definition of a features list class template. typename... A type sequence of logger features.

This class template can be used to specify logger features in a ``basic_composite_logger`` instantiation.

Andrey Semashev

21.04.2008

The header contains implementation of facilities to declare global loggers. The macro forward-declares a global logger with a custom initialization. The macro defines a global logger initialization routine. The macro defines a global logger initializer that will default-construct the logger. The macro defines a global logger initializer that will construct the logger with the specified constructor arguments. The macro declares a global logger with a custom initialization. The macro declares a global logger that will be default-constructed. The macro declares a global logger that will be constructed with the specified arguments.

Andrey Semashev

08.03.2007

The header contains implementation of a simplistic logger with no features. basic_composite_logger< char, logger, single_thread_model, features< > >Narrow-char logger. Functionally equivalent to ``basic_logger``.

See ``basic_logger`` class template for a more detailed description.

Narrow-char thread-safe logger. Functionally equivalent to ``basic_logger``.

See ``basic_logger`` class template for a more detailed description.

basic_composite_logger< wchar_t, wlogger, single_thread_model, features< > >Wide-char logger. Functionally equivalent to ``basic_logger``.

See ``basic_logger`` class template for a more detailed description.

Wide-char thread-safe logger. Functionally equivalent to ``basic_logger``.

See ``basic_logger`` class template for a more detailed description.

Andrey Semashev

09.03.2009

This header contains a wrapper class around a logging record that allows to compose the record message with a streaming expression. basic_formatting_ostream< CharT >Logging record adapter with a streaming capability.

This class allows to compose the logging record message by streaming operations. It aggregates the log record and provides the standard output stream interface.

Character type. CharT String type to be used as a message text holder. std::basic_string< char_type > Stream type. std::basic_ostream< char_type > bool

Conversion to an unspecified boolean type

`true`, if stream is valid and ready for formatting, `false`, if the stream is not valid. The latter also applies to the case when the stream is not attached to a log record.

bool

Inverted conversion to an unspecified boolean type

`false`, if stream is valid and ready for formatting, `true`, if the stream is not valid. The latter also applies to the case when the stream is not attached to a log record.

record &

Flushes internal buffers to complete all pending formatting operations and returns the aggregated log record

The aggregated record object

record const &

Flushes internal buffers to complete all pending formatting operations and returns the aggregated log record

The aggregated record object

void `record &

New log record to attach to

`

If the stream is attached to a log record, flushes internal buffers to complete all pending formatting operations. Then reattaches the stream to another log record.

void The function resets the stream into a detached (default initialized) state.

Default constructor. Creates an empty record that is equivalent to the invalid record handle. The stream capability is not available after construction.

`!*this == true`

`record &

The record handle being attached to

`

Constructor from a record object. Attaches to the provided record.

`!!rec == true`

`&this->get_record() == &rec`

Destructor. Destroys the record, releases any sinks and attribute values that were involved in processing this record.

void The function initializes the stream and the stream buffer. ``basic_record_ostream` const &` `basic_record_ostream` &``basic_record_ostream` const &` Convenience typedef for narrow-character logging. `basic_record_ostream`< char > Convenience typedef for wide-character logging. `basic_record_ostream`< wchar_t > `unspecified `StreamT &``T const &`` `unspecified `StreamT &``T &`` `unspecified `StreamT &&``T const &`` `unspecified `StreamT &&``T &`` The macro writes a record to the log. The macro writes a record to the log and allows to pass additional named arguments to the logger. An equivalent to BOOST_LOG_STREAM(logger) An equivalent to BOOST_LOG_STREAM_WITH_PARAMS(logger, params_seq)

Andrey Semashev

28.02.2008

The header contains implementation of a logger with severity level and channel support. int std::string basic_composite_logger< char, severity_channel_logger< LevelT, ChannelT >, single_thread_model, features< severity< LevelT >, channel< ChannelT > > >Narrow-char logger. Functionally equivalent to ``basic_severity_logger`` and ``basic_channel_logger``.

See `severity` and `channel` class templates for a more detailed description

Default constructor

``severity_channel_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`severity_channel_logger` &``severity_channel_logger` const &`

Assignment operator

Swaps two loggers

int std::string basic_composite_logger< char, severity_channel_logger_mt< LevelT, ChannelT >, multi_thread_model< implementation_defined >, features< severity< LevelT >, channel< ChannelT > > >Narrow-char thread-safe logger. Functionally equivalent to ``basic_severity_logger`` and ``basic_channel_logger``.

See `severity` and `channel` class templates for a more detailed description

Default constructor

``severity_channel_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`severity_channel_logger_mt` &``severity_channel_logger_mt` const &`

Assignment operator

Swaps two loggers

int std::wstring basic_composite_logger< wchar_t, wseverity_channel_logger< LevelT, ChannelT >, single_thread_model, features< severity< LevelT >, channel< ChannelT > > >Wide-char logger. Functionally equivalent to ``basic_severity_logger`` and ``basic_channel_logger``.

See `severity` and `channel` class templates for a more detailed description

Default constructor

``wseverity_channel_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`wseverity_channel_logger` &``wseverity_channel_logger` const &`

Assignment operator

Swaps two loggers

int std::wstring basic_composite_logger< wchar_t, wseverity_channel_logger_mt< LevelT, ChannelT >, multi_thread_model< implementation_defined >, features< severity< LevelT >, channel< ChannelT > > >Wide-char thread-safe logger. Functionally equivalent to ``basic_severity_logger`` and ``basic_channel_logger``.

See `severity` and `channel` class templates for a more detailed description

Default constructor

``wseverity_channel_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`wseverity_channel_logger_mt` &``wseverity_channel_logger_mt` const &`

Assignment operator

Swaps two loggers

The macro allows to put a record with a specific channel name into log.
An equivalent to BOOST_LOG_STREAM_CHANNEL_SEV(logger, chan, lvl)

Andrey Semashev

08.03.2007

The header contains implementation of a severity level support feature. int Severity level feature implementation. Character type. base_type::char_type Final type. base_type::final_type Threading model being used. base_type::threading_model Severity level type. LevelT Severity attribute type. unspecified Lock requirement for the `open_record_unlocked` method. strictest_lock< typename base_type::open_record_lock, no_lock< threading_model > >::type Lock requirement for the `swap_unlocked` method. unspecified severity_level

Default severity value getter

Default constructor. The constructed logger will have a severity attribute registered. The default level for log records will be 0.

``basic_severity_logger` const &`

Copy constructor

``basic_severity_logger` &&`

Move constructor

`ArgsT const &

A set of named arguments. The following arguments are supported:

- `severity` - default severity value

`

Constructor with named arguments. Allows to setup the default level for log records.

severity_attribute const &

Severity attribute accessor

record `ArgsT const &`

Unlocked `open_record`

void``basic_severity_logger` &`Unlocked `swap`. int Severity level support feature.

The logger with this feature registers a special attribute with an integral value type on construction. This attribute will provide severity level for each log record being made through the logger. The severity level can be omitted on logging record construction, in which case the default level will be used. The default level can also be customized by passing it to the logger constructor.

The type of the severity level attribute can be specified as a template parameter for the feature template. By default, `int` will be used.

`basic_severity_logger`< BaseT, LevelT > The macro allows to put a record with a specific severity level into log. An equivalent to BOOST_LOG_STREAM_SEV(logger, lvl)

Andrey Semashev

08.03.2007

The header contains implementation of a logger with severity level support. int basic_composite_logger< char, severity_logger< LevelT >, single_thread_model, features< severity< LevelT > > >Narrow-char logger. Functionally equivalent to ``basic_severity_logger``.

See `severity` class template for a more detailed description

Default constructor

``severity_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`LevelT

The default severity level

`

The constructor creates the logger with the specified default severity level

`severity_logger` &``severity_logger` const &`

Assignment operator

Swaps two loggers

int basic_composite_logger< char, severity_logger_mt< LevelT >, multi_thread_model< implementation_defined >, features< severity< LevelT > > >Narrow-char thread-safe logger. Functionally equivalent to ``basic_severity_logger``.

See `severity` class template for a more detailed description

Default constructor

``severity_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`LevelT

The default severity level

`

The constructor creates the logger with the specified default severity level

`severity_logger_mt` &``severity_logger_mt` const &`

Assignment operator

Swaps two loggers

int basic_composite_logger< wchar_t, wseverity_logger< LevelT >, single_thread_model, features< severity< LevelT > > >Wide-char logger. Functionally equivalent to ``basic_severity_logger``.

See `severity` class template for a more detailed description

Default constructor

``wseverity_logger` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`LevelT

The default severity level

`

The constructor creates the logger with the specified default severity level

`wseverity_logger` &``wseverity_logger` const &`

Assignment operator

Swaps two loggers

int basic_composite_logger< wchar_t, wseverity_logger_mt< LevelT >, multi_thread_model< implementation_defined >, features< severity< LevelT > > >Wide-char thread-safe logger. Functionally equivalent to ``basic_severity_logger``.

See `severity` class template for a more detailed description

Default constructor

``wseverity_logger_mt` const &`

Copy constructor

typename... `ArgsT...const &`

Constructor with named arguments

`LevelT

The default severity level

`

The constructor creates the logger with the specified default severity level

`wseverity_logger_mt` &``wseverity_logger_mt` const &`

Assignment operator

Swaps two loggers

Andrey Semashev

04.10.2008

The header contains definition of threading models that can be used in loggers. The header also provides a number of tags that can be used to express lock requirements on a function callee. Single thread locking model. void bool bool `TimeT const &` void void bool bool `TimeT const &` void void bool bool `TimeT const &` void void void void void void``single_thread_model` &` Multi-thread locking model with maximum locking capabilities. void bool bool `TimeT const &` void void bool bool `TimeT const &` void void bool bool `TimeT const &` void void void void void void``multi_thread_model` &` ``multi_thread_model` const &` `multi_thread_model` &``multi_thread_model` const &`