File Logger.hpp¶
Defines
-
ACTS_DEBUG(x)¶
macro for debug debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::DEBUG.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
ACTS_ERROR(x)¶
macro for error debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::ERROR.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
ACTS_FATAL(x)¶
macro for fatal debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::FATAL.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
ACTS_INFO(x)¶
macro for info debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::INFO.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
ACTS_LOCAL_LOGGER(log_object)¶
macro to use a local Acts::Logger object
This macro allows to use a locally defined logging object with the ACTS_* logging macros. The envisaged usage is the following:
void myFunction() { std::unique_ptr<const Acts::Logger> myLogger = /* .. your initialization .. */; ACTS_LOCAL_LOGGER(std::move(myLogger)); ACTS_VERBOSE("hello world!"); }
- Parameters
log_object – logger instance of type
- Pre
In the current scope, the symbol
logger
is not yet defined.- Post
The ownership of the given
log_object
is transferred andlog_object
should not be used directly any more.
-
ACTS_LOG(level, x)¶
-
ACTS_VERBOSE(x)¶
macro for verbose debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::VERBOSE.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
ACTS_WARNING(x)¶
macro for warning debug output
The debug message is printed if the current Acts::Logging::Level <= Acts::Logging::WARNING.
- Parameters
x – debug message
- Pre
logger()
must be a valid expression in the scope where this macro is used and it must return a Acts::Logger object.
-
namespace Acts
Note
This file is foreseen for the
Geometry
module to replaceExtent
Note
this is foreseen for the ‘Geometry’ module
Functions
-
std::unique_ptr<const Logger> getDefaultLogger(const std::string &name, const Logging::Level &lvl, std::ostream *log_stream = &std::cout)¶
get default debug output logger
This function returns a pointer to a Logger instance with the following decorations enabled:
time stamps
name of logging instance
debug level
- Parameters
name – [in] name of the logger instance
lvl – [in] debug threshold level
log_stream – [in] output stream used for printing debug messages
- Returns
pointer to logging instance
-
class Logger
- #include <Acts/Utilities/Logger.hpp>
class for printing debug output
This class provides the user interface for printing debug messages with different levels of severity.
Public Functions
-
inline Logger(std::unique_ptr<Logging::OutputPrintPolicy> pPrint, std::unique_ptr<Logging::OutputFilterPolicy> pFilter)
construct from output print and filter policy
- Parameters
pPrint – [in] policy for printing debug messages
pFilter – [in] policy for filtering debug messages
-
inline std::unique_ptr<Logger> clone(const std::optional<std::string> &_name = std::nullopt, const std::optional<Logging::Level> &_level = std::nullopt) const
Make a copy of this logger, optionally changing the name or the level.
- Parameters
_name – the optional new name
_level – the optional new level
-
inline std::unique_ptr<Logger> clone(Logging::Level _level) const
Make a copy of the logger, with a new level.
Convenience function for if you only want to change the level but not the name.
- Parameters
_level – the new level
- Returns
the new logger
-
inline std::unique_ptr<Logger> cloneWithSuffix(const std::string &suffix, std::optional<Logging::Level> _level = std::nullopt) const
Make a copy of the logger, with a suffix added to the end of it’s name.
You can also optionally supply a new level
- Parameters
suffix – the suffix to add to the end of the name
_level – the optional new level
-
inline bool doPrint(const Logging::Level &lvl) const
decide whether a message with a given debug level has to be printed
- Parameters
lvl – [in] debug level of debug message
- Returns
true
if debug message should be printed, otherwisefalse
-
inline const Logging::OutputFilterPolicy &filterPolicy() const
Return the filter policy for this logger.
- Returns
the filter policy
-
inline Logging::Level level() const
Return the level of the filter policy of this logger.
- Returns
the level
-
inline void log(const Logging::Level &lvl, const std::string &input) const
log a debug message
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline const std::string &name() const
Return the name of the print policy of thi logger.
- Returns
the name
-
inline const Logger &operator()() const
Helper function so a logger reference can be used as is with the logging macros.
-
inline const Logging::OutputPrintPolicy &printPolicy() const
Return the print policy for this logger.
- Returns
the print policy
Private Members
-
std::unique_ptr<Logging::OutputFilterPolicy> m_filterPolicy¶
policy object for filtering debug messages
-
std::unique_ptr<Logging::OutputPrintPolicy> m_printPolicy¶
policy object for printing debug messages
-
inline Logger(std::unique_ptr<Logging::OutputPrintPolicy> pPrint, std::unique_ptr<Logging::OutputFilterPolicy> pFilter)
-
namespace Logging¶
debug output related helper classes and functions
Enums
-
enum Level¶
constants steering the debug output
All messages with a debug level equal or higher than the currently set debug output level will be printed.
Values:
-
enumerator VERBOSE¶
VERBOSE level.
-
enumerator DEBUG¶
DEBUG level.
-
enumerator INFO¶
INFO level.
-
enumerator WARNING¶
WARNING level.
-
enumerator ERROR¶
ERROR level.
-
enumerator FATAL¶
FATAL level.
-
enumerator MAX¶
Must be kept above the maximum supported debug level.
-
enumerator VERBOSE¶
Functions
-
Level getFailureThreshold()¶
Get debug level above which an exception will be thrown after logging.
All messages with a debug level equal or higher than the return value of this function will cause an exception to be thrown after log emission.
Note
Depending on preprocessor settings
ACTS_ENABLE_LOG_FAILURE_THRESHOLD
andACTS_LOG_FAILURE_THRESHOLD
, this operations is either constexpr or a runtime operation.
-
void setFailureThreshold(Level level)¶
Set debug level above which an exception will be thrown after logging.
All messages with a debug level equal or higher than
level
will cause an exception to be thrown after log emission.Note
This function is only available if
ACTS_LOG_FAILURE_THRESHOLD
is unset, i.e. no compile-time threshold is used. Otherwise an exception is thrown.Warning
The runtime log failure threshold is global state, therefore this function is not threadsafe. The intention is that this level is set once, before multi-threaded execution begins, and then not modified before the end of the job.
-
class DefaultFilterPolicy : public Acts::Logging::OutputFilterPolicy
- #include <Acts/Utilities/Logger.hpp>
default filter policy for debug messages
All debug messages with a debug level equal or larger to the specified threshold level are processed.
Public Functions
-
inline explicit DefaultFilterPolicy(Level lvl)
constructor
- Parameters
lvl – [in] threshold debug level
-
~DefaultFilterPolicy() override = default
virtual default destructor
-
inline virtual std::unique_ptr<OutputFilterPolicy> clone(Level level) const override
Make a copy of this filter policy with a new level.
- Parameters
level – the new level
- Returns
the new copy
-
inline virtual bool doPrint(const Level &lvl) const override
decide whether a debug message should be processed
- Parameters
lvl – [in] debug level of debug message
- Returns
true
iflvl
>= m_level, otherwisefalse
-
inline virtual Level level() const override
Get the level of this filter policy.
- Returns
the levele
-
inline explicit DefaultFilterPolicy(Level lvl)
-
class DefaultPrintPolicy : public Acts::Logging::OutputPrintPolicy
- #include <Acts/Utilities/Logger.hpp>
default print policy for debug messages
This class allows to print debug messages without further modifications to a specified output stream.
Public Functions
-
inline explicit DefaultPrintPolicy(std::ostream *out = &std::cout)
constructor
- Parameters
out – [in] pointer to output stream object
- Pre
out
is non-zero
-
inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
inline virtual void flush(const Level &lvl, const std::string &input) final
flush the debug message to the destination stream
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline virtual const std::string &name() const override
Fulfill
OutputPrintPolicy
interface.This policy doesn’t actually have a name, so the assumption is that somewhere in the decorator hierarchy, there is something that returns a name without delegating to a wrappee, before reaching this overload.
Note
This method will throw an exception
- Returns
the name, but it never returns
Private Members
-
std::ostream *m_out¶
pointer to destination output stream
-
inline explicit DefaultPrintPolicy(std::ostream *out = &std::cout)
-
class LevelOutputDecorator : public Acts::Logging::OutputDecorator
- #include <Acts/Utilities/Logger.hpp>
decorate debug message with its debug level
The debug message is complemented with its debug level.
Public Functions
-
inline explicit LevelOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
constructor
- Parameters
wrappee – [in] output print policy object to be wrapped
-
inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
inline virtual void flush(const Level &lvl, const std::string &input) override
flush the debug message to the destination stream
This function prepends the debug level to the debug message and then delegates the flushing of the whole message to its wrapped object.
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline explicit LevelOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
-
class NamedOutputDecorator : public Acts::Logging::OutputDecorator
- #include <Acts/Utilities/Logger.hpp>
decorate debug message with a name
The debug message is complemented with a name.
Public Functions
-
inline NamedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &name, unsigned int maxWidth = 15)
constructor
- Parameters
wrappee – [in] output print policy object to be wrapped
name – [in] name to be added to debug message
maxWidth – [in] maximum width of field used for name
-
inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
inline virtual void flush(const Level &lvl, const std::string &input) override
flush the debug message to the destination stream
This function prepends the given name to the debug message and then delegates the flushing of the whole message to its wrapped object.
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline virtual const std::string &name() const override
Get this named output decorators name.
- Returns
the name
-
inline NamedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &name, unsigned int maxWidth = 15)
-
class OutputDecorator : public Acts::Logging::OutputPrintPolicy
- #include <Acts/Utilities/Logger.hpp>
base class for decorating the debug output
Derived classes may augment the debug message with additional information. Chaining different decorators is possible to customize the output to your needs.
Subclassed by Acts::Logging::LevelOutputDecorator, Acts::Logging::NamedOutputDecorator, Acts::Logging::ThreadOutputDecorator, Acts::Logging::TimedOutputDecorator
Public Functions
-
inline explicit OutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
constructor wrapping actual output print policy
- Parameters
wrappee – [in] output print policy object which is wrapped by this decorator object
-
inline virtual void flush(const Level &lvl, const std::string &input) override
flush the debug message to the destination stream
This function delegates the flushing of the debug message to its wrapped object.
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline virtual const std::string &name() const override
Return the name of the output decorator (forwards to wrappee)
- Returns
the name
Protected Attributes
-
std::unique_ptr<OutputPrintPolicy> m_wrappee¶
wrapped object for printing the debug message
-
inline explicit OutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
-
class OutputFilterPolicy
- #include <Acts/Utilities/Logger.hpp>
abstract base class for filtering debug output
Implementations of this interface need to define whether a debug message with a certain debug level is processed or filtered out.
Subclassed by Acts::Logging::DefaultFilterPolicy
Public Functions
-
virtual ~OutputFilterPolicy() = default
virtual default destructor
-
virtual std::unique_ptr<OutputFilterPolicy> clone(Level level) const = 0
Make a copy of this filter policy with a new level.
- Parameters
level – the new level
- Returns
the new copy
-
virtual bool doPrint(const Level &lvl) const = 0
decide whether a debug message should be processed
- Parameters
lvl – [in] debug level of debug message
- Returns
true
of debug message should be processed,false
if debug message should be skipped
-
virtual Level level() const = 0
Get the level of this filter policy.
- Returns
the levele
-
virtual ~OutputFilterPolicy() = default
-
class OutputPrintPolicy
- #include <Acts/Utilities/Logger.hpp>
abstract base class for printing debug output
Implementations of this interface need to define how and where to print debug messages (e.g. to a file, to a stream into a database etc).
Subclassed by Acts::Logging::DefaultPrintPolicy, Acts::Logging::OutputDecorator
Public Functions
-
virtual ~OutputPrintPolicy() = default
virtual default destructor
-
virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const = 0
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
virtual void flush(const Level &lvl, const std::string &input) = 0
handle output of debug message
- Parameters
lvl – [in] debug output level of message
input – [in] text of debug message
-
virtual const std::string &name() const = 0
Return the name of the print policy.
- Returns
the name
-
virtual ~OutputPrintPolicy() = default
-
class ThreadOutputDecorator : public Acts::Logging::OutputDecorator
- #include <Acts/Utilities/Logger.hpp>
decorate debug message with a thread ID
The debug message is complemented with a thread ID.
Public Functions
-
inline explicit ThreadOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
constructor
- Parameters
wrappee – [in] output print policy object to be wrapped
-
inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
inline virtual void flush(const Level &lvl, const std::string &input) override
flush the debug message to the destination stream
This function prepends the thread ID to the debug message and then delegates the flushing of the whole message to its wrapped object.
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
-
inline explicit ThreadOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)
-
class ThresholdFailure : public std::runtime_error
- #include <Acts/Utilities/Logger.hpp>
Custom exception class so threshold failures can be caught.
-
class TimedOutputDecorator : public Acts::Logging::OutputDecorator
- #include <Acts/Utilities/Logger.hpp>
decorate debug message with a time stamp
The debug message is complemented with a time stamp.
Public Functions
-
inline TimedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &format = "%X")
constructor
- Parameters
wrappee – [in] output print policy object to be wrapped
format – [in] format of time stamp (see std::strftime)
-
inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override
Make a copy of this print policy with a new name.
- Parameters
name – the new name
- Returns
the copy
-
inline virtual void flush(const Level &lvl, const std::string &input) override
flush the debug message to the destination stream
This function prepends a time stamp to the debug message and then delegates the flushing of the whole message to its wrapped object.
- Parameters
lvl – [in] debug level of debug message
input – [in] text of debug message
Private Functions
-
inline std::string now() const¶
get current time stamp
- Returns
current time stamp as string
Private Members
-
std::string m_format¶
format of the time stamp (see std::strftime for details)
-
inline TimedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &format = "%X")
-
enum Level¶
-
std::unique_ptr<const Logger> getDefaultLogger(const std::string &name, const Logging::Level &lvl, std::ostream *log_stream = &std::cout)¶