4.4.0
|
|
Freundlich's C++ toolkit |
Logging classes and functions.
Link to ${fcppt_log_TARGET}
, or to fcppt_log_interface
if you only need the headers.
The following list highlights the main features of fcppt's logging library:
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.
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.
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:
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.
Here is a more detailed explanation of how log messages are formatted and where they are written to:
std::basic_ostream
as its log destination. Where output actually ends up is decided by its streambuf. 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:
We are also going to create another formatting function for the error level stream that logs to fcppt::io::cerr.
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.
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.
Finally, we create the log object that uses the aforementioned formatting function:
The following code shows what is printed:
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.
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
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"}
.
The child object gets the name "child"
and the root object passed to its constructor, thus its location is {"root", "child"}
.
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:
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.
Here we change the child location to only have the warning level and every level above enabled, so the following output is not printed:
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:
Passing an empty optional log level disables all levels.
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.
All headers are relative to the log subdirectory.
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. |
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. | |
#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.
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
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.
using fcppt::log::name = typedef fcppt::strong_typedef< fcppt::string ,_> |
The name of a logger.
using fcppt::log::format::optional_function = typedef fcppt::optional::object<fcppt::log::format::function> |
using fcppt::log::optional_level = typedef fcppt::optional::object<fcppt::log::level> |
An optional level.
using fcppt::log::format::prefix_string = typedef fcppt::strong_typedef< fcppt::string ,_> |
using fcppt::log::format::suffix_string = typedef fcppt::strong_typedef< fcppt::string ,_> |
|
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.
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.
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.
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.
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::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.
name | the name of the log level |
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.
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 fcppt::io::istream & fcppt::log::operator>> | ( | fcppt::io::istream & | , |
fcppt::log::level & | |||
) |
Reads a level from a stream.
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.
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.
|
extern |
Trampoline to create logger output.
Use this object to output to a log stream.