carb::logging::ILogging

Defined in carb/logging/ILogging.h

struct ILogging

Defines the log system that is associated with the Framework.

This interface defines the log system, which is a singleton object. It can be used at any moment, including before the startup of the Framework and after the Framework was shutdown. It allows a user to setup the logging behavior in advance and allows the Framework to log during its initialization.

Logger - is an interface for logging backend. ILogging can contain multiple Loggers and every message will be passed to every logger. There is one implementation of a Logger provided - StandardLogger. It can log into file, console and debug window. ILogging starts up with one instance of StandardLogger2, which can be retrieved by calling getDefaultLogger(). It is added by default, but can be removed with getLogging()->removeLogger(getLogging()->getDefaultLogger()->getLogger()).

ILogging supports multiple sources of log messages. Source is just a name to differentiate the origins of a message. Every plugin, application and Framework itself are different sources. However user can add more custom sources if needed.

Use the logging macros from Log.h for all logging in applications and plugins.

There are 2 log settings: log level (to control log severity threshold) and log enabled (to toggle whole logging). Both of them can be set globally and per source.

Public Functions

inline ObjectPtr<StandardLogger2> createStandardLogger()

Creates a new StandardLogger2 instance.

Use this method to create additional StandardLogger2 instances. This can be useful when you want to log to multiple output destinations but want different configuration for each. Pass the value from StandardLogger2::getLogger() to addLogger() to make it active. When finished with the StandardLogger2 call StandardLogger2::release().

Returns

A new StandardLogger2.

Public Members

void (*log)(const char *source, int32_t level, const char *fileName, const char *functionName, int lineNumber, const char *fmt, ...)

Logs a formatted message to the specified log source and log level.

This API is used primarily by the CARB_LOG_XXXX macros.

Param source

The log source to log the message to.

Param level

The level to log the message at.

Param fileName

The file name to log to.

Param functionName

The name of the function where the message originated from.

Param lineNumber

The line number

Param fmt

The print formatted message.

Param …

The variable arguments for the formatted message variables.

void (*setLevelThreshold)(int32_t level)

Sets global log level threshold.

Messages below this threshold will be dropped.

Param level

The log level to set.

int32_t (*getLevelThreshold)()

Gets global log level threshold.

Messages below this threshold will be dropped.

Return

Global log level.

void (*setLogEnabled)(bool enabled)

Sets global log enabled setting.

Param enabled

Global log enabled setting.

bool (*isLogEnabled)()

If global log is enabled.

Return

Global log enabled.

void (*setLevelThresholdForSource)(const char *source, LogSettingBehavior behavior, int32_t level)

Sets log level threshold for the specified source.

Messages below this threshold will be dropped. Per source log settings can either inherit global or override it, it is configured with LogSettingBehavior::eInherit and LogSettingBehavior::eOverride accordingly.

Param source

The source to set log level setting for. Must not be nullptr.

Param behavior

The log setting behavior for the source.

Param level

The log level to set. This param is ignored if behavior is set to LogSettingBehavior::eInherit.

void (*setLogEnabledForSource)(const char *source, LogSettingBehavior behavior, bool enabled)

Sets log enabled setting for the specified source.

Per source log settings can either inherit global or override it, it is configured with LogSettingBehavior::eInherit and LogSettingBehavior::eOverride accordingly.

Param source

The source to set log enabled setting for. Must not be nullptr.

Param behavior

The log setting behavior for the source.

Param enabled

The log enabled setting. This param is ignored if behavior is set to LogSettingBehavior::eInherit.

void (*reset)()

Reset all log settings set both globally and per source.

Log system resets to the defaults: log is enabled and log level is ‘warn’.

void (*addLogger)(Logger *logger)

Adds a logger to the ILogging.

See also

StandardLogger2::getLogger()

Param logger

The logger to be added.

void (*removeLogger)(Logger *logger)

Removes the logger from the ILogging.

See also

StandardLogger2::getLogger()

Param logger

The logger to be removed.

StandardLogger *(*getDefaultLoggerOld)()

Accesses the default logger.

This logger can be disabled by passing it to removeLogger(). This logger is owned by the logging system and cannot be destroyed by passing it to destroyStandardLoggerOld().

• Deprecated since version 156.0.

• Use getDefaultLogger() instead

Return

the default logger.

StandardLogger *(*createStandardLoggerOld)()

Creates a new StandardLogger instance.

Use this method to create additional StandardLogger instances. This can be useful when you want to log to multiple output destinations but want different configuration for each. Use addLogger() to make it active. When finished with the StandardLogger pass it to destroyStandardLoggerOld().

• Deprecated since version 156.0.

• Use createStandardLogger() instead

Return

A new StandardLogger.

void (*destroyStandardLoggerOld)(StandardLogger *logger)

Use this method to destroy a StandardLogger that was created via createStandardLoggerOld().

• Deprecated since version 156.0.

• The StandardLogger2 that replaces StandardLogger can be destroyed by calling release().

Param logger

The logger to be destroyed.

void (*registerSource)(const char *source, SetLogLevelFn setLevelThreshold)

Register new logging source.

This function is mainly automatically used by plugins, application and the Framework itself to create their own logging sources.

Custom logging source can also be created if needed. It is the user’s responsibility to call ILogging::unregisterSource in that case.

It is the source responsibility to track its log level. The reason is that it allows to filter out logging before calling into the logging system, thus making the performance cost for the disabled logging negligible. It is done by providing a callback setLevelThreshold to be called by ILogging when any setting which influences this source is changed.

Param source

The source name. Must not be nullptr.

Param setLevelThreshold

The callback to be called to update log level. ILogging::unregisterSource must be called when the callback is no longer valid.

void (*unregisterSource)(const char *source)

Unregister logging source.

Param source

The source name. Must not be nullptr.

bool (*setLogAsync)(bool logAsync)

Instructs the logging system to deliver all log messages to the Logger backends asynchronously.

Async logging is OFF by default.

This causes log() calls to be buffered so that log() may return as quickly as possible. A background thread then issues these buffered log messages to the registered Logger backend objects.

Param logAsync

True to use async logging; false to disable async logging.

Return

true if was previously using async logging; false if was previously using synchronous logging.

bool (*getLogAsync)()

Returns whether the ILogging system is using async logging.

Return

true if currently using async logging; false if currently using synchronous logging

void (*flushLogs)()

When ILogging is in async mode, wait until all log messages have flushed out to the various loggers.

StandardLogger2 *(*getStandardLogger2)(StandardLogger *logger)

Retrieves the extended StandardLogger2 interface from an old StandardLogger instance.

Param logger

The logger to retrieve the instance from. If nullptr then nullptr will be returned.

Return

The StandardLogger2 interface for logger, or nullptr.

StandardLogger2 *(*getDefaultLogger)()

Accesses the default logger.

This logger can be disabled by passing the underlying logger (from StandardLogger2::getLogger()) to removeLogger(). This logger is owned by the logging system and calling StandardLogger2::release() has no effect.

Return

the default StandardLogger2.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns

The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns

The carb::InterfaceDesc struct with information about the latest version of this interface.