Description

Logging classes and functions.

Link to ${fcppt_log_TARGET}, or to fcppt_log_interface if you only need the headers.

Introduction

The following list highlights the main features of fcppt's logging library:

Configuration of enabled output:

The library assigns log levels to log locations, which is stored by a log context. Log levels are, for example, debug, warning, error and log locations are lists of strings.

Formatting and direction of messages:

A log context also assigns to each log level a level stream, which dictates where to log to, e.g. to std::clog, and how messages are formatted.

A simple example

The class that does actual logging is called fcppt::log::object. It refers to an fcppt::log::location in a fcppt::log::context. The following example illustrates the use of a simple log object:

  // Create a log context that has debug and every level above enabled
  fcppt::log::context context{
      fcppt::log::optional_level{fcppt::log::level::debug}, fcppt::log::default_level_streams()};
 
  // Create a log object at location "{ fcppt }"
  fcppt::log::object log{
      fcppt::make_ref(context),
      fcppt::log::parameters{
          fcppt::log::name{FCPPT_TEXT("fcppt")}, fcppt::log::format::optional_function{}}};
 
  // Outputs "fcppt: debug: Hello World"
  if (log.enabled(fcppt::log::level::debug))
  {
    log.log(fcppt::log::level::debug, fcppt::log::out << FCPPT_TEXT("Hello World"));
  }
 
  // The same as above using a shorthand macro
  FCPPT_LOG_DEBUG(log, fcppt::log::out << FCPPT_TEXT("Hello World"))
 
  // This is not printed because the verbose level is not enabled
  FCPPT_LOG_VERBOSE(log, fcppt::log::out << FCPPT_TEXT("Very verbose message"))

Logging is done via the fcppt::log::object::log element function. The macro FCPPT_LOG_DEBUG is a short-hand for logging only if the debug log level is enabled. This is important because the construction of the log message is avoided altogether when debug is not enabled.

fcppt::log::out is an object that basically acts like a std::basic_ostream. This is used to create a whole message in a thread-safe manner. If you log in multiple pieces instead, the log message might end up interleaved with other messages.

Formatting and sinks

Formatting design

Here is a more detailed explanation of how log messages are formatted and where they are written to:

A log context contains an fcppt::log::level_stream for every log level. Each of them controls where output is written to and how it is formatted.
Each level stream uses an std::basic_ostream as its log destination. Where output actually ends up is decided by its streambuf.
Formatting is done through #fcppt::log::format::function objects which can be naturally chained together. Every log object and every level stream can have their own formatters.

Formatting and sinks example

In the following example, we are going to give our log object a special formatting function that prints This is a formatting test: in front of every log message.

Such a formatting function takes a string and returns a string and can be implemented as follows:

fcppt::string log_formatter(fcppt::string const &_text)
{
  return FCPPT_TEXT("This is a formatting test: ") + _text;
}

We are also going to create another formatting function for the error level stream that logs to fcppt::io::cerr.

 
// Create a formatter for the error log level. Note that we have to append a
// newline here, because this is normally done by the default formatters for
// each log level.
fcppt::string error_formatter(fcppt::string const &_text)
{
  return FCPPT_TEXT("Horrible error, please fix: ") + _text + FCPPT_TEXT('\n');
}

We then create the level streams, such that the error level logs to fcppt::io::cerr using the error function we just created. Every other level logs to fcppt::io::cout using the default formatting function.

  auto const level_streams(
      fcppt::enum_::array_init<fcppt::log::level_stream_array>([](fcppt::log::level const _level) {
        // Create a special sink for the error log level that prints to
        // cerr and also has a special formatter.
        return _level == fcppt::log::level::error
                   ? fcppt::log::level_stream(
                         fcppt::io::cerr(),
                         fcppt::log::format::optional_function{
                             fcppt::log::format::function{error_formatter}})
                   : fcppt::log::level_stream(
                         fcppt::io::cout(),
                         fcppt::log::format::optional_function(
                             fcppt::log::format::default_level(_level)));
      }));

The log context we are going to use again has the debug level and every level above enabled. Instead of fcppt::log::default_level_streams we give it the level streams we just created.

  fcppt::log::context context{
      fcppt::log::optional_level{fcppt::log::level::debug},
      fcppt::log::level_stream_array{level_streams}};

Finally, we create the log object that uses the aforementioned formatting function:

  fcppt::log::object log{
      fcppt::make_ref(context),
      fcppt::log::parameters{
          fcppt::log::name{FCPPT_TEXT("fcppt")},
          // Create a special formatter for the whole log
          fcppt::log::format::optional_function{fcppt::log::format::function{log_formatter}}}};

The following code shows what is printed:

  // Prints:
  // 'This is a formatting test: fcppt: debug: test'
  // to cout.
  FCPPT_LOG_DEBUG(log, fcppt::log::out << FCPPT_TEXT("test"))
 
  // Prints:
  // 'This is a formatting test: fcppt: Horrible error, please fix: some error'
  // to cerr.
  FCPPT_LOG_ERROR(log, fcppt::log::out << FCPPT_TEXT("some error"))

Log hierarchy

Controlling at runtime which messages are logged is very important. Under normal circumstances, you probably want to only log serious problems, while in a debug scenario a lot of debug messages should be logged.

Log hierarchy design

A location is a list of fcppt::log::name values, e.g. {"my_lib", "my_subsystem"}. An fcppt::log::context associates locations with fcppt::log::optional_level values. These can be configured through the fcppt::log::context::set function, even before any log objects are created. This is useful, for example, for specifying log levels on the command line.

Each log object refers to a location of a given context. In its constructor, it gets a name, and in addition to that, it gets either

a log context, in which case its location is its name,
a log context and a location, in which case its location is the given location plus its name, or
a parent log object, in which case its location is the parent's location plus its own name.

Log hierarchy example

The next example shows how log objects, contexts and locations can be used together.

The log context gets a single fcppt::log::optional_level as its parameter, which is used as a default for every location, unless changed.

fcppt::log::context context{

fcppt::log::optional_level{fcppt::log::level::debug}, fcppt::log::default_level_streams()};

We declare a root object with name "root". Its location will be {"root"}.

  fcppt::log::name const root_name{FCPPT_TEXT("root")};
 
  fcppt::log::object root_log{
      fcppt::make_ref(context),
      fcppt::log::parameters(root_name, fcppt::log::format::optional_function{})};

The child object gets the name "child" and the root object passed to its constructor, thus its location is {"root", "child"}.

  fcppt::log::name const child_name{FCPPT_TEXT("child")};
 
  fcppt::log::object child_log{
      root_log, fcppt::log::parameters(child_name, fcppt::log::format::optional_function{})};

As mentioned earlier, the locations inherit the root level of the context, so every log object currently has the debug level and all levels above enabled: The log location given to a log object implicitly changes how its output is formatted:

  FCPPT_LOG_INFO(root_log, fcppt::log::out << FCPPT_TEXT("Print from root!"))
 
  FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("Print from child!"))

The first statement will print root: warning: Print from root. and the second statement will print root: child: warning: Print from child.

The fcppt::log::context::set function can be used to change the level of a location at runtime.

  context.set(
      fcppt::log::location{root_name} / child_name,
      fcppt::log::optional_level{fcppt::log::level::warning});

Here we change the child location to only have the warning level and every level above enabled, so the following output is not printed:

FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("shouldn't be shown!"))

Note that changing the level at a location also changes the levels below it. We can change the root level back to debug which will also affect the child level:

  context.set(
      fcppt::log::location{root_name}, fcppt::log::optional_level{fcppt::log::level::debug});
 
  FCPPT_LOG_INFO(child_log, fcppt::log::out << FCPPT_TEXT("This is now shown!"))

Passing an empty optional log level disables all levels.

Thread safety

The log context contains a mutex to protect its internal structure from race conditions. Therefore, calling element functions of a log context from multiple threads is safe. Log objects can be used in different threads than the log context. However, sharing a log object between different threads is not safe.

Header files

All headers are relative to the log subdirectory.

Essential header files

Header file	Description
`out.hpp`	Contains fcppt::log::out .
`context_fwd.hpp`	Contains fcppt::log::context 's declaration.
`context.hpp`	Contains fcppt::log::context 's definition.
`debug.hpp`	Contains the FCPPT_LOG_DEBUG macro.
`error.hpp`	Contains the FCPPT_LOG_ERROR macro.
`fatal.hpp`	Contains the FCPPT_LOG_FATAL macro.
`info.hpp`	Contains the FCPPT_LOG_INFO macro.
`level.hpp`	Contains the fcppt::log::level enumeration.
`location_fwd.hpp`	Contains fcppt::log::location 's declaration.
`location.hpp`	Contains fcppt::log::location 's definition.
`name_fwd.hpp`	Contains `fcppt::log::name`'s declaration.
`name.hpp`	Contains `fcppt::log::name`'s definition.
`object_fwd.hpp`	Contains fcppt::log::object 's declaration.
`object.hpp`	Contains fcppt::log::object 's defintiion.
`parameters_fwd.hpp`	Contains fcppt::log::parameters 's declaration.
`parameters.hpp`	Contains fcppt::log::parameters 's definition.
`verbose.hpp`	Contains the FCPPT_LOG_VERBOSE macro.
`warning.hpp`	Contains the FCPPT_LOG_WARNING macro.

Other header files

Header file	Description
`default_level_streams.hpp`	Contains fcppt::log::default_level_streams for construction of all level stream defaults.
`default_stream.hpp`	Contains the fcppt::log::default_stream function.
`level_from_string.hpp`	Contains fcppt::log::level_from_string .
`level_stream_array.hpp`	Contains the fcppt::log::level_stream_array typedef.
`level_stream_fwd.hpp`	Contains fcppt::log::level_stream 's declaration.
`level_stream.hpp`	Contains fcppt::log::level_stream 's definition.
`level_to_string.hpp`	Contains fcppt::log::level_to_string .
`optional_level_fwd.hpp`	Contains the fcppt::log::optional_level typedef.
`optional_level.hpp`	Includes `optional_level_fwd.hpp` and optional headers.
`format/chain.hpp`	Contains the #fcppt::log::format::chain function.
`format/default_level.hpp`	Contains the #fcppt::log::format::default_level function.
`format/format.hpp`	Includes all headers of `log/format`.
`format/function_fwd.hpp`	Contains the #fcppt::log::format::function typedef.
`format/function.hpp`	Includes `format/function_fwd.hpp` and function headers.
`format/inserter.hpp`	Contains the #fcppt::log::format::inserter typedef.
`format/prefix.hpp`	Contains the #fcppt::log::format::prefix function.
`format/time_stamp.hpp`	Contains the #fcppt::log::format::time_stamp typedef.

Classes
class	fcppt::log::context
	A logger context manages log levels. More...

class	fcppt::log::level_stream
	The stream for a logger level. More...

class	fcppt::log::location
	A location of a logger in a context. More...

class	fcppt::log::object
	The main log class. More...

class	fcppt::log::parameters
	The parameters class for an fcppt::log::object. More...

Macros
#define	FCPPT_LOG_DEBUG(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::debug, output)
	Log to a stream if its debug level is enabled.

#define	FCPPT_LOG_ERROR(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::error, output)
	Log to a stream if its error level is enabled.

#define	FCPPT_LOG_FATAL(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::fatal, output)
	Log to a stream if its fatal level is enabled.

#define	FCPPT_LOG_INFO(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::info, output)
	Log to a stream if its info level is enabled.

#define	FCPPT_LOG_VERBOSE(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::verbose, output)
	Log to a stream if its verbose level is enabled.

#define	FCPPT_LOG_WARNING(stream, output) FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::warning, output)
	Log to a stream if its warning level is enabled.

Typedefs
using	fcppt::log::format::function = fcppt::function< fcppt::string(fcppt::string)>
	A formatter function object.

using	fcppt::log::format::optional_function = fcppt::optional::object< fcppt::log::format::function >

using	fcppt::log::format::prefix_string = fcppt::strong_typedef< fcppt::string,_ >

using	fcppt::log::format::suffix_string = fcppt::strong_typedef< fcppt::string,_ >

using	fcppt::log::level_stream_array = fcppt::enum_::array< fcppt::log::level, fcppt::log::level_stream >
	An array used to save log level streams for every level.

using	fcppt::log::name = fcppt::strong_typedef< fcppt::string,_ >
	The name of a logger.

using	fcppt::log::optional_level = fcppt::optional::object< fcppt::log::level >
	An optional level.

Enumerations
enum class	fcppt::log::level { fcppt::log::level::verbose , fcppt::log::level::debug , fcppt::log::level::info , fcppt::log::level::warning , fcppt::log::level::error , fcppt::log::level::fatal , fcppt::log::level::fcppt_maximum = fatal }
	An enumeration for the available log levels. More...

Functions
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::level_stream_array	fcppt::log::default_level_streams ()
	Constructs the default level streams.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::optional_function	fcppt::log::format::chain (fcppt::log::format::optional_function const &parent, fcppt::log::format::optional_function const &child)
	Composes two formatters.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function	fcppt::log::format::default_level (fcppt::log::level level)
	Creates a default formatter for a level stream.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function	fcppt::log::format::inserter (fcppt::log::format::prefix_string const &, fcppt::log::format::suffix_string const &)
	Creates a formatter from a prefix and a suffix.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function	fcppt::log::format::prefix (fcppt::log::format::prefix_string const &prefix)
	Creates a prefix formatter.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function	fcppt::log::format::time_stamp ()
	Creates a formatter that prints a time stamp.

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::optional_level	fcppt::log::level_from_string (fcppt::string_view name)
	Converts the name of a log level to its enum.

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::istream &	fcppt::log::operator>> (fcppt::io::istream &, fcppt::log::level &)
	Reads a level from a stream.

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::ostream &	fcppt::log::operator<< (fcppt::io::ostream &, fcppt::log::level)
	Outputs a level to a stream.

FCPPT_LOG_DETAIL_SYMBOL std::string_view	fcppt::log::level_to_string (fcppt::log::level)
	Converts a log level to its string representation.

Variables
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::detail::output_helper const	fcppt::log::out
	Trampoline to create logger output.

Macro Definition Documentation

◆ FCPPT_LOG_DEBUG

#define FCPPT_LOG_DEBUG	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::debug, output)

Log to a stream if its debug level is enabled.

◆ FCPPT_LOG_ERROR

#define FCPPT_LOG_ERROR	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::error, output)

Log to a stream if its error level is enabled.

◆ FCPPT_LOG_FATAL

#define FCPPT_LOG_FATAL	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::fatal, output)

Log to a stream if its fatal level is enabled.

◆ FCPPT_LOG_INFO

#define FCPPT_LOG_INFO	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::info, output)

Log to a stream if its info level is enabled.

◆ FCPPT_LOG_VERBOSE

#define FCPPT_LOG_VERBOSE	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::verbose, output)

Log to a stream if its verbose level is enabled.

◆ FCPPT_LOG_WARNING

#define FCPPT_LOG_WARNING	(	stream,
		output
	)	FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(stream, fcppt::log::level::warning, output)

Log to a stream if its warning level is enabled.

Typedef Documentation

◆ function

using fcppt::log::format::function = typedef fcppt::function<fcppt::string(fcppt::string)>

A formatter function object.

This object gets a string from which it returns a new string

◆ level_stream_array

using fcppt::log::level_stream_array = typedef fcppt::enum_::array<fcppt::log::level, fcppt::log::level_stream>

An array used to save log level streams for every level.

An array of fcppt::log::level_stream with the size fcppt::log::level. Each entry corresponds to an enumerator from fcppt::log::level.

◆ name

using fcppt::log::name = typedef fcppt::strong_typedef< fcppt::string ,_>

The name of a logger.

◆ optional_function

using fcppt::log::format::optional_function = typedef fcppt::optional::object<fcppt::log::format::function>

◆ optional_level

using fcppt::log::optional_level = typedef fcppt::optional::object<fcppt::log::level>

An optional level.

◆ prefix_string

using fcppt::log::format::prefix_string = typedef fcppt::strong_typedef< fcppt::string ,_>

◆ suffix_string

using fcppt::log::format::suffix_string = typedef fcppt::strong_typedef< fcppt::string ,_>

Enumeration Type Documentation

◆ level

enum class fcppt::log::level

strong

An enumeration for the available log levels.

Every enumerator state here represents a less serious log level than the next one. For example, info is less serious than warning. size itself is not a valid log level.

Enumerator
verbose	Used for verbose messages. Verbose is the lowest log level, and so it should be used without any reserve.
debug	Used for debug messages. The debug log level should be used whenever information is required that is only useful during debugging and would be too verbose otherwise.
info	Used for info messages. The info log level should be used whenever information is required that is not too verbose. It is a good candidate to activate as default log level.
warning	Used for warning messages. The warning log level should be used whenever something must be printed that is important for the user to read, but most of the time doesn't lead to any errors. It is not recommended to turn this off.
error	Used for error messages. The error log level should be used whenever an error occurs, but it is still possible for the system to handle the situation. It is not recommended to turn this off.
fatal	Used for fatal messages. The fatal log level should be used whenever an error occurs that cannot be handled.
fcppt_maximum	The maximum value of the enumeration.

Function Documentation

◆ chain()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::optional_function fcppt::log::format::chain	(	fcppt::log::format::optional_function const &	parent,
		fcppt::log::format::optional_function const &	child
	)

Composes two formatters.

Creates a formatter that composes parent and child in the following way: If parent and child are not nothing, their functions are composed (parent (.) child). Otherwise, if parent is not nothing, parent is returned. Otherwise, child is returned.

◆ default_level()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::default_level ( fcppt::log::level level )

Creates a default formatter for a level stream.

Creates a default formatter for a level stream with the level of level. This formatter prints the level's string in front as obtained by fcppt::log::level_to_string. It also appends a newline at the end.

◆ default_level_streams()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::level_stream_array fcppt::log::default_level_streams ( )

Constructs the default level streams.

Each level stream uses #fcppt::log::format::default_level as its formatter and fcppt::log::default_stream as its stream.

◆ inserter()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::inserter	(	fcppt::log::format::prefix_string const &	,
		fcppt::log::format::suffix_string const &
	)

Creates a formatter from a prefix and a suffix.

◆ level_from_string()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::optional_level fcppt::log::level_from_string ( fcppt::string_view name )

Converts the name of a log level to its enum.

Converts the name of a log level given by name to its corresponding level enumerator. Accepts all strings as parameters that are listed in fcppt::log::level.

Parameters

name	the name of the log level

◆ level_to_string()

FCPPT_LOG_DETAIL_SYMBOL std::string_view fcppt::log::level_to_string ( fcppt::log::level )

Converts a log level to its string representation.

Converts a log level given by level to its enumerator name as a string.

◆ operator<<()

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::ostream & fcppt::log::operator<<	(	fcppt::io::ostream &	,
		fcppt::log::level
	)

Outputs a level to a stream.

◆ operator>>()

FCPPT_LOG_DETAIL_SYMBOL fcppt::io::istream & fcppt::log::operator>>	(	fcppt::io::istream &	,
		fcppt::log::level &
	)

Reads a level from a stream.

◆ prefix()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::prefix ( fcppt::log::format::prefix_string const & prefix )

Creates a prefix formatter.

Creates a formatter that outputs prefix in front.

◆ time_stamp()

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::time_stamp ( )

Creates a formatter that prints a time stamp.

Creates a formatter that prints a time stamp in front.

Variable Documentation

◆ out

FCPPT_LOG_DETAIL_SYMBOL fcppt::log::detail::output_helper const fcppt::log::out

extern

Trampoline to create logger output.

Use this object to output to a log stream.

	4.4.1
Freundlich's C++ toolkit