Logging

How to log messages

There are several logging methods available in the logging module. The methods are designed to only cause call overhead when obscura is built with the DEBUG flag. The methods are:

template<typename StringType, typename ...Args> inline void obscura::logInfo(StringType fmt, const Args&... args)

Logs an info message.

The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logWarn(StringType fmt, const Args&... args)

Logs a warning message.

The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logError(StringType fmt, const Args&... args)

Logs an error message.

The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logDebug(StringType fmt, const Args&... args)

Logs a debug message.

The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logTrace(StringType fmt, const Args&... args)

Logs a trace message.

The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

Internally, a different set of methods is used to log messages. These methods are:

template<typename StringType, typename ...Args> inline void obscura::logCoreInfo(StringType fmt, const Args&... args)

Logs an info message.

Should only be used internally by obscura. For logging in the client code, use logInfo. The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logCoreWarn(StringType fmt, const Args&... args)

Logs a warning message.

Should only be used internally by obscura. For logging in the client code, use logWarn. The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logCoreError(StringType fmt, const Args&... args)

Logs an error message.

Should only be used internally by obscura. For logging in the client code, use logError. The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logCoreDebug(StringType fmt, const Args&... args)

Logs a debug message.

Should only be used internally by obscura. For logging in the client code, use logDebug. The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

template<typename StringType, typename ...Args> inline void obscura::logCoreTrace(StringType fmt, const Args&... args)

Logs a trace message.

Should only be used internally by obscura. For logging in the client code, use logTrace. The function is only called if logging is enabled. If the pre-processing variable is set to false, the function does not cause any function call overhead.

Template Parameters:

StringType – The type of the string to log.
Args – The types of the arguments to log.

Parameters:

fmt – The format string.
args – The arguments to log.

Example

#include <obscura/obscura.hxx>

// Define a custom logger. We first define a custom logger implementation and then a custom logger that is a singleton
class CustomLoggerImpl: public obscura::BaseLoggerImpl {
  public:
    CustomLoggerImpl()
      : obscura::BaseLoggerImpl("Custom") {
    }
};

// In order to not have multiple logger instances, we define a singleton for the custom logger
class CustomLogger: public obscura::Singleton<CustomLoggerImpl> { };

// Define a custom log function. This function will log messages using the custom logger. The function should be inline
// to avoid function call overhead in case the inner constexpr condition is false.
template<typename StringType, typename... Args>
inline void logCustomInfo(StringType fmt, const Args&... args) {
    if constexpr (obscura::loggingEnabled) {
        CustomLogger::getInstance().info(fmt, args...);
    }
}

auto main() -> int {
    // Use these log functions to log messages from your obscura applications
    obscura::logInfo("This is an info message.");
    obscura::logWarn("This is a warning message.");
    obscura::logError("This is an error message.");
    obscura::logDebug("This is a debug message.");
    obscura::logTrace("This is a trace message.");

    // You can also format your log messages
    obscura::logInfo("This is a test with the string '{}' and the int {}", "haha", 12);

    // If you want to use a custom logger, define a custom logger as seen above and use the logCustom functions
    logCustomInfo("This is a custom info message.");

    // If you are contributing to obscura and logging from the core of the library, use these log functions
    obscura::logCoreInfo("This is an info message from the core of the library.");
    obscura::logCoreWarn("This is a warning message from the core of the library.");
    obscura::logCoreError("This is an error message from the core of the library.");
    obscura::logCoreDebug("This is a debug message from the core of the library.");
    obscura::logCoreTrace("This is a trace message from the core of the library.");

    return EXIT_SUCCESS;
}