ILogging#

Fully qualified name: carb::logging::ILogging

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.

template<typename T> inline bool modifyExtraFieldValue( const char *key, T value, ExtraFieldFlags flags = fExtraFieldFlagNone, )#

Adds, removes, or modifies a specific extra field for logs.

Remark

This allows an extra field to be added or modified. Any time a log message is emitted, all of the extra fields that exist at the time for the emitting thread (global fields list plus the list for the calling thread). The standard logger will add the extra field strings at the start of the log message text itself. It will be passed to all log loggers (ie: carb::logging::Logger2) and log consumers (ie: omni::log::ILogMessageConsumer2). Each global extra field will be surrounded by square brackets (ie: ‘[]’), with the format “[<key>:<value>]”. Thread specific extra fields will follow the same format except they will be surrounded with round brackets (ie: ‘()’). The ordering of the extra fields in the log output will be undefined, but the order will remain stable as long as no change to the extra fields list is made.

Note

The thread-specific extra fields are not fiber aware and will therefore emit the extra fields belonging to the thread the fiber is running on instead of the fields added by the fiber itself. This includes the fibers used for carb.tasking tasks and omni.job jobs. If extra fields are needed from a task or job, they should be added inside the tasks function then removed before the task switches away or unschedules itself.

Parameters:

key – [in] The key name of the extra field to operate on. The specific operation depends on the value in flags and value. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
value – [in] The new value to set for the given extra field. This may be nullptr to remove the extra field with the given key name.
flags – [in] Flags to control how this operation will proceed. This may be any combination of the ExtraFieldFlags flags.

Returns:

true if the requested extra field is added or modified successfully. Returns Returns false if adding or modifying the value of the extra field fails for any reason (ie: memory allocation, etc).

template<typename T> inline bool addExtraField( const char *key, T value, ExtraFieldFlags flags = fExtraFieldFlagNone, )#

Adds an extra field key/value pair.

Parameters:

key – [in] The key name of the extra field to add. The flags parameter controls which list (global or per-thread) this new extra field is is added to. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
value – [in] The new value to set for the given extra field. This may not be nullptr.
flags – [in] Flags to control which extra fields list will be added to. This may be either fExtraFieldFlagGlobal or fExtraFieldFlagThread.

Returns:

true if the new value is sucessfully added. Returns false otherwise.

inline bool removeExtraField( const char *key, ExtraFieldFlags flags = fExtraFieldFlagNone, )#

Removes an extra field based on its key name.

Parameters:

key – [in] The key name of the extra field to remove. The flags parameter controls which list (global or per-thread) this extra field will be removed from. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
flags – [in] Flags to control which extra fields list this key should be removed from. This may be either fExtraFieldFlagGlobal or fExtraFieldFlagThread.

Returns:

true if the specified key/value pair was successfully removed from the requested list. Returns false if the key was not found in the specified list.

inline bool hasExtraField( const char *key, ExtraFieldFlags flags = fExtraFieldFlagNone, )#

Tests whether a given extra field exists.

Parameters:

key – [in] The key name of the extra field to check if it exists in the given list. This may not be an empty string or nullptr.
flags – [in] Flags specifying which list the named extra field is expected to be tested as being in. This should be either fExtraFieldFlagGlobal or fExtraFieldFlagThread.

Returns:

true if the named extra field currently exists in the requested list. Returns false if the named extra field does not exist yet.

template<> inline bool modifyExtraFieldValue( const char *key, const char *value, ExtraFieldFlags flags, )#

Adds, removes, or modifies a specific extra field for logs.

Remark

This allows an extra field to be added or modified. Any time a log message is emitted, all of the extra fields that exist at the time for the emitting thread (global fields list plus the list for the calling thread). The standard logger will add the extra field strings at the start of the log message text itself. It will be passed to all log loggers (ie: carb::logging::Logger2) and log consumers (ie: omni::log::ILogMessageConsumer2). Each global extra field will be surrounded by square brackets (ie: ‘[]’), with the format “[<key>:<value>]”. Thread specific extra fields will follow the same format except they will be surrounded with round brackets (ie: ‘()’). The ordering of the extra fields in the log output will be undefined, but the order will remain stable as long as no change to the extra fields list is made.

Note

The thread-specific extra fields are not fiber aware and will therefore emit the extra fields belonging to the thread the fiber is running on instead of the fields added by the fiber itself. This includes the fibers used for carb.tasking tasks and omni.job jobs. If extra fields are needed from a task or job, they should be added inside the tasks function then removed before the task switches away or unschedules itself.

Parameters:

key – [in] The key name of the extra field to operate on. The specific operation depends on the value in flags and value. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
value – [in] The new value to set for the given extra field. This may be nullptr to remove the extra field with the given key name.
flags – [in] Flags to control how this operation will proceed. This may be any combination of the ExtraFieldFlags flags.

Returns:

true if the requested extra field is added or modified successfully. Returns Returns false if adding or modifying the value of the extra field fails for any reason (ie: memory allocation, etc).

template<> inline bool modifyExtraFieldValue( const char *key, std::nullptr_t value, ExtraFieldFlags flags, )#

Adds, removes, or modifies a specific extra field for logs.

Remark

This allows an extra field to be added or modified. Any time a log message is emitted, all of the extra fields that exist at the time for the emitting thread (global fields list plus the list for the calling thread). The standard logger will add the extra field strings at the start of the log message text itself. It will be passed to all log loggers (ie: carb::logging::Logger2) and log consumers (ie: omni::log::ILogMessageConsumer2). Each global extra field will be surrounded by square brackets (ie: ‘[]’), with the format “[<key>:<value>]”. Thread specific extra fields will follow the same format except they will be surrounded with round brackets (ie: ‘()’). The ordering of the extra fields in the log output will be undefined, but the order will remain stable as long as no change to the extra fields list is made.

Note

The thread-specific extra fields are not fiber aware and will therefore emit the extra fields belonging to the thread the fiber is running on instead of the fields added by the fiber itself. This includes the fibers used for carb.tasking tasks and omni.job jobs. If extra fields are needed from a task or job, they should be added inside the tasks function then removed before the task switches away or unschedules itself.

Parameters:

key – [in] The key name of the extra field to operate on. The specific operation depends on the value in flags and value. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
value – [in] The new value to set for the given extra field. This may be nullptr to remove the extra field with the given key name.
flags – [in] Flags to control how this operation will proceed. This may be any combination of the ExtraFieldFlags flags.

Returns:

true if the requested extra field is added or modified successfully. Returns Returns false if adding or modifying the value of the extra field fails for any reason (ie: memory allocation, etc).

template<> inline bool addExtraField( const char *key, const char *value, ExtraFieldFlags flags, )#

Adds an extra field key/value pair.

Parameters:

key – [in] The key name of the extra field to add. The flags parameter controls which list (global or per-thread) this new extra field is is added to. This may not be an empty string or nullptr. This key name should only contain alphanumeric printable characters and should be as short as possible while still being uniquely identifying.
value – [in] The new value to set for the given extra field. This may not be nullptr.
flags – [in] Flags to control which extra fields list will be added to. This may be either fExtraFieldFlagGlobal or fExtraFieldFlagThread.

Returns:

true if the new value is sucessfully added. Returns false otherwise.

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

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.

void (*addLogger)(Logger2 *logger)#

Adds a logger to the ILogging.