2.10.0
Freundlich's C++ toolkit
Classes | Macros | Typedefs | Enumerations | Functions | Variables
fcppt.log

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
},
};
// Create a log object at location "{ fcppt }"
context,
FCPPT_TEXT("fcppt")
},
}
};
// Outputs "fcppt: debug: Hello World"
if(
log.enabled(
)
)
log.log(
<< FCPPT_TEXT("Hello World")
);
// The same as above using a shorthand macro
log,
<< FCPPT_TEXT("Hello World")
)
// This is not printed because the verbose level is not enabled
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:

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:

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.
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.

fcppt::log::level_stream_array const level_streams(
>(
[](
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
==
?
error_formatter
}
}
)
:
_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.

},
level_streams
};

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

context,
FCPPT_TEXT("fcppt")
},
// Create a special formatter for the whole log
log_formatter
}
}
}
};

The following code shows what is printed:

// Prints:
// 'This is a formatting test: fcppt: debug: test'
// to cout.
log,
<< FCPPT_TEXT("test")
)
// Prints:
// 'This is a formatting test: fcppt: Horrible error, please fix: some error'
// to cerr.
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

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.

},
};

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

fcppt::log::name const root_name{
FCPPT_TEXT("root")
};
context,
root_name,
)
};

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,
child_name,
)
};

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:

root_log,
<< FCPPT_TEXT("Print from root!")
)
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(
root_name
}
/
child_name,
}
);

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

child_log,
<< 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(
root_name
},
}
);
child_log,
<< 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)
 Log to a stream if its debug level is enabled. More...
 
#define FCPPT_LOG_ERROR(stream, output)
 Log to a stream if its error level is enabled. More...
 
#define FCPPT_LOG_FATAL(stream, output)
 Log to a stream if its fatal level is enabled. More...
 
#define FCPPT_LOG_INFO(stream, output)
 Log to a stream if its info level is enabled. More...
 
#define FCPPT_LOG_VERBOSE(stream, output)
 Log to a stream if its verbose level is enabled. More...
 
#define FCPPT_LOG_WARNING(stream, output)
 Log to a stream if its warning level is enabled. More...
 

Typedefs

typedef fcppt::function< fcppt::string(fcppt::string)> fcppt::log::format::function
 A formatter function object. More...
 
typedef fcppt::optional::object< fcppt::log::format::functionfcppt::log::format::optional_function
 
typedef fcppt::strong_typedef< fcppt::string,_ > fcppt::log::format::prefix_string
 
typedef fcppt::strong_typedef< fcppt::string,_ > fcppt::log::format::suffix_string
 
typedef fcppt::enum_::array< fcppt::log::level, fcppt::log::level_streamfcppt::log::level_stream_array
 An array used to save log level streams for every level. More...
 
typedef fcppt::strong_typedef< fcppt::string,_ > fcppt::log::name
 The name of a logger. More...
 
typedef fcppt::optional::object< fcppt::log::levelfcppt::log::optional_level
 An optional level. More...
 

Enumerations

enum  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. More...
 
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. More...
 
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. More...
 
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. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::prefix (fcppt::log::format::prefix_string const &prefix)
 Creates a prefix formatter. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::format::function fcppt::log::format::time_stamp ()
 Creates a formatter that prints a time stamp. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::log::optional_level fcppt::log::level_from_string (fcppt::string const &name)
 Converts the name of a log level to its enum. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::io::istreamfcppt::log::operator>> (fcppt::io::istream &, fcppt::log::level &)
 Reads a level from a stream. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::io::ostreamfcppt::log::operator<< (fcppt::io::ostream &, fcppt::log::level)
 Outputs a level to a stream. More...
 
FCPPT_LOG_DETAIL_SYMBOL fcppt::string fcppt::log::level_to_string (fcppt::log::level)
 Converts a log level to its string representation. More...
 

Variables

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

Macro Definition Documentation

◆ FCPPT_LOG_DEBUG

#define FCPPT_LOG_DEBUG (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for debug messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its debug level is enabled.

◆ FCPPT_LOG_ERROR

#define FCPPT_LOG_ERROR (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for error messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its error level is enabled.

◆ FCPPT_LOG_FATAL

#define FCPPT_LOG_FATAL (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for fatal messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its fatal level is enabled.

◆ FCPPT_LOG_INFO

#define FCPPT_LOG_INFO (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for info messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its info level is enabled.

◆ FCPPT_LOG_VERBOSE

#define FCPPT_LOG_VERBOSE (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for verbose messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its verbose level is enabled.

◆ FCPPT_LOG_WARNING

#define FCPPT_LOG_WARNING (   stream,
  output 
)
Value:
FCPPT_LOG_DETAIL_LEVEL_IF_ENABLED(\
stream,\
)
Used for warning messages.
fcppt::container::detail::output< Container > output(Container const &_container) noexcept
Creates a class that has an output operator to print a container.
Definition: output.hpp:36

Log to a stream if its warning level is enabled.

Typedef Documentation

◆ function

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

A formatter function object.

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

◆ level_stream_array

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

The name of a logger.

◆ optional_function

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

◆ optional_level

An optional level.

◆ prefix_string

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

◆ suffix_string

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

Enumeration Type Documentation

◆ level

enum 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 const &  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
namethe name of the log level

◆ level_to_string()

FCPPT_LOG_DETAIL_SYMBOL fcppt::string 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 like fcppt::log::format::time_stamp does.

Variable Documentation

◆ out

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

Trampoline to create logger output.

Use this object to output to a log stream.