omni::log::ILog¶
Defined in omni/log/ILog.h
-
class
omni::log
::
ILog
: public omni::core::Generated<omni::log::ILog_abi>¶ Multi-channel logging interface which can write logs to multiple consumers.
See the Omniverse Logging Guide to better understand how logging works from both the user’s and developer’s point-of-view.
In practice, use of this interface is hidden to the user. Most logging occurs via the following macros:
The macros above internally call omniGetLogWithoutAcquire(), which returns an omni::log::ILog pointer. See omniGetLogWithoutAcquire() for details on how to control which omni::log::ILog pointer is returned.
The logging interface defines two concepts: log channels and log consumers.
Log channels are identified by a string and represent the idea of a logging “channel”. Each channel has a:
Enabled/Disabled flag (see omni::log::ILog::setChannelEnabled()).
Log level at which messages should be ignored (see omni::log::ILog::setChannelLevel()).
Each message logged is associated with a single log channel.
Each time a message is logged, the channel’s settings are checked to see if the message should be filtered out. If the message is not filtered, the logging interface formats the message and passes it to each log message consumer.
Log consumers (e.g. omni::log::ILogMessageConsumer) are attached to the logging system via omni::log::ILog::addMessageConsumer(). Along with the formatted message, log consumers are passed a bevvy of additional information, such as filename, line number, channel name, message level, etc. The consumer may choose to perform additional filtering at this point. Eventually, it is up to the log consumer to “log” the message to its backing store (e.g.
stdout
).The omni::log::ILog interface itself has a global enable/disabled flag and log level. Each channel can choose to respect the global flags (via omni::log::SettingBehavior::eInherit) or override the global flags with their own (via omni::log::SettingBehavior::eOverride).
With these settings, user have fine-grain control over which messages are filtered and where messages are logged.
See OMNI_LOG_ADD_CHANNEL() for information on creating and registering log channels.
In order to support rich user experiences, the logging system also allows consumers to be notified of internal state changes such as a channel being added, the logging level changing, etc. See omni::log::ILog::addChannelUpdateConsumer() for details.
Public Functions
-
std::vector<omni::core::ObjectPtr<omni::log::ILogMessageConsumer>>
getMessageConsumers
() noexcept¶ Returns a snapshot of the array of message consumers attached to the log.
- Thread Safety
This method is thread safe.
-
std::vector<omni::core::ObjectPtr<omni::str::IReadOnlyCString>>
getChannelNames
() noexcept¶ Returns a snapshot of the array of channels attached to the log.
- Thread Safety
This method is thread safe.
-
std::vector<omni::core::ObjectPtr<omni::log::ILogChannelUpdateConsumer>>
getChannelUpdateConsumers
() noexcept¶ Returns a snapshot of the array of update consumers attached to the log.
- Thread Safety
This method is thread safe.
-
template<const char *
T
>
inline voidsetChannelEnabled
(const omni::log::LogChannel<T> &channel, bool isEnabled, omni::log::SettingBehavior behavior) noexcept¶ Sets the given channel’s enabled/disabled flag.
If the channel has not yet been registered with omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.
- Thread Safety
This method is thread safe.
-
template<const char *
T
>
inline omni::core::ResultgetChannelEnabled
(const omni::log::LogChannel<T> &channel, bool *outEnabled, omni::log::SettingBehavior *outBehavior) noexcept¶ Returns the given channel’s logging enabled state and override behavior.
All parameters must be non-
nullptr
.If the given channel is not found, an omni::core::kResultNotFound is returned.
Return omni::core::kResultSuccess upon success, a failure code otherwise.
- Thread Safety
This method is thread safe.
-
template<const char *
T
>
inline voidsetChannelLevel
(const omni::log::LogChannel<T> &channel, omni::log::Level level, omni::log::SettingBehavior behavior) noexcept¶ Sets the given channel’s log level.
If the channel has not yet been registered with omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.
- Thread Safety
This method is thread safe.
-
template<const char *
T
>
inline omni::core::ResultgetChannelLevel
(const omni::log::LogChannel<T> &channel, omni::log::Level *outLevel, omni::log::SettingBehavior *outBehavior) noexcept¶ Returns the given channel’s logging level and override behavior.
All parameters must be non-
nullptr
.If the given channel is not found, an omni::core::kResultNotFound is returned.
- Thread Safety
This method is thread safe.
- Returns
Returns omni::core::kResultSuccess upon success, a failure code otherwise.
-
template<const char *
T
>
inline boolisLoggingAtLevel
(const omni::log::LogChannel<T> &channel, omni::log::Level level)¶ Given a channel and a verbosity level, returns
true
if the channel is actively logging at the given level.Using the
OMNI_LOG_*
macros is preferred over this method, as those macros use a much more efficient method to filter messages. However, the mechanics utilized byOMNI_LOG_*
are not viable when binding to languages such as Python, thus this method’s existence.- Thread Safety
This method is thread safe.
-
inline void
log
(const char *channel, omni::log::Level level, const char *moduleName, const char *fileName, const char *functionName, uint32_t lineNumber, const char *str, uint32_t strCharCount) noexcept¶ Sends the supplied message to all registered omni::log::ILogMessageConsumer objects.
- Parameters
str – Must be a
\0
terminated string.strCharCount – The number of characters in
str
(including the terminating\0
). IfstrCharCount
is 0, its value will be computed by this method.
-
inline void
logf
(const char *channel, omni::log::Level level, const char *moduleName, const char *fileName, const char *functionName, uint32_t lineNumber, const char *format, ...) noexcept¶ Formats the supplied message and sends the result to all registered omni::log::ILogMessageConsumer objects.
-
inline void
addMessageConsumer
(omni::core::ObjectParam<omni::log::ILogMessageConsumer> consumer) noexcept¶ Adds the given log consumer to the internal list of log consumers.
Each message is associated with a single log channel. When a message is logged by a log channel, the message is checked to see if it should be filtered. If not, it is given to the logging system (omni::log::ILog) which eventually sends the message to each registered omni::log::ILogMessageConsumer.
A consumer can be registered a single time with a given omni::log::ILog instance but can be registered with multple omni::log::ILog instances.
Each message may be sent to registered consumers in parallel.
Logging a message from a consumer callback will lead to undefined behavior.
Calling omni::log::ILog::addMessageConsumer() from omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.
- Thread Safety
This method is thread safe.
-
inline omni::core::ObjectPtr<omni::log::ILogMessageConsumer>
addMessageConsumer
(std::function<void(const char *channel, omni::log::Level level, const char *moduleName, const char *fileName, const char *functionName, uint32_t lineNumber, const char *msg, carb::thread::ProcessId pid, carb::thread::ThreadId tid, uint64_t timestamp)> fun) noexcept¶ Adds the given log consumer to the internal list of log consumers.
Each message is associated with a single log channel. When a message is logged by a log channel, the message is checked to see if it should be filtered. If not, it is given to the logging system (omni::log::ILog) which eventually sends the message to each registered omni::log::ILogMessageConsumer.
A consumer can be registered a single time with a given omni::log::ILog instance but can be registered with multple omni::log::ILog instances.
Each message may be sent to registered consumers in parallel.
Logging a message from a consumer callback will lead to undefined behavior.
Calling omni::log::ILog::addMessageConsumer() from omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.
- Thread Safety
This method is thread safe.
-
inline void
removeMessageConsumer
(omni::core::ObjectParam<omni::log::ILogMessageConsumer> consumer) noexcept¶ Removes the given consumer from the internal consumer list.
This method silently accepts
nullptr
.This method silently accepts consumers that have not been registered with this object.
Calling omni::log::ILog::removeMessageConsumer() from omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.
- Thread Safety
This method is thread safe.
-
inline void
setLevel
(omni::log::Level level) noexcept¶ Set the logging level of this object.
By default log channels obey the logging level set on this object. However, this behavior can be overriden with omni::log::ILog::setChannelLevel().
- Thread Safety
This method is thread safe.
-
inline omni::log::Level
getLevel
() noexcept¶ Returns the logging level of this object.
- Thread Safety
This method is thread safe.
-
inline void
setEnabled
(bool isEnabled) noexcept¶ Set if the log is enabled/disabled.
By default log channels obey the enable/disabled flag set on this object. However, this behavior can be overriden with omni::log::ILog::setChannelEnabled().
- Thread Safety
This method is thread safe.
-
inline bool
isEnabled
() noexcept¶ Returns if the log is enabled/disabled.
- Thread Safety
This method is thread safe.
-
inline bool
setAsync
(bool logAsync) noexcept¶ Instructs the logging system to deliver all log messages to the logging backends asynchronously.
This causes omni::log::ILog::log() calls to be buffered so that omni::log::ILog::log() may return as quickly as possible. A background thread then issues these buffered log messages to the registered Logger backend objects.
- Thread Safety
This method is thread safe.
- Returns
Returns the state of asynchronous logging before this method was called.
-
inline bool
isAsync
() noexcept¶ Returns
true
if asynchronous logging is enabled.- Thread Safety
This method is thread safe.
-
inline void
addChannel
(const char *name, omni::log::Level *level, const char *description) noexcept¶ Associates a log channel’s id with a chunk of memory to store its settings.
A log channel can be registered multiple times. In fact, this is quite common, as a log channel’s settings are usually stored per-module and a log channel may span multiple modules.
When registering a channel via this API, the given setting’s memory is updated.
- Thread Safety
This method is thread safe.
- Parameters
name – Name of the channel. Copied by this method.
level – Pointer to where the channels level is stored. The pointer must point to valid memory until omni::log::ILog::removeChannel() is called.
description – The description of the channel. Can be
nullptr
. If notnullptr
, and a description for the channel is already set and not empty, the given description is ignored. Otherwise, the description is copied by this method.
-
inline void
removeChannel
(const char *name, omni::log::Level *level) noexcept¶ Removes a log channel’s settings memory.
Use this method when unloading a module to prevent the log writing settings to unloaded memory.
- Thread Safety
This method is thread safe.
-
inline void
setChannelLevel
(const char *name, omni::log::Level level, omni::log::SettingBehavior behavior) noexcept¶ Sets the given channel’s log level.
If the channel has not yet been registered with omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.
- Thread Safety
This method is thread safe.
-
inline omni::core::Result
getChannelLevel
(const char *name, omni::log::Level *outLevel, omni::log::SettingBehavior *outBehavior) noexcept¶ Returns the given channel’s logging level and override behavior.
All parameters must be non-
nullptr
.If the given channel is not found, an omni::core::kResultNotFound is returned.
- Thread Safety
This method is thread safe.
- Returns
Returns omni::core::kResultSuccess upon success, a failure code otherwise.
-
inline void
setChannelEnabled
(const char *name, bool isEnabled, omni::log::SettingBehavior behavior) noexcept¶ Sets the given channel’s enabled/disabled flag.
If the channel has not yet been registered with omni::log::ILog::addChannel(), the setting will be remembered and applied when the channel is eventually added.
- Thread Safety
This method is thread safe.
-
inline omni::core::Result
getChannelEnabled
(const char *name, bool *outIsEnabled, omni::log::SettingBehavior *outBehavior) noexcept¶ Returns the given channel’s logging enabled state and override behavior.
All parameters must be non-
nullptr
.If the given channel is not found, an omni::core::kResultNotFound is returned.
Return omni::core::kResultSuccess upon success, a failure code otherwise.
- Thread Safety
This method is thread safe.
-
inline void
setChannelDescription
(const char *name, const char *description) noexcept¶ Sets a channel’s description. If the channel does not exists, it is created.
The given channel
name
anddescription
must not benullptr
.The memory pointed to by
description
is copied by this method.If the channel already has a description, it is replaced.
- Thread Safety
This method is thread safe.
-
inline omni::core::Result
getChannelDescription
(const char *name, omni::str::IReadOnlyCString **outDescription) noexcept¶ Returns the given channel’s description.
All parameters must be non-
nullptr
.When calling this method,
*outDescription
must benullptr
.If the channel does not have a description set,
*outDescription
is set tonullptr
.If
*outDescripton
is set to non-nullptr
, it will have omni::core::IObject::acquire() called on it before it is passed back to the caller.If the given channel is not found, an omni::core::kResultNotFound is returned.
- Thread Safety
This method is thread safe.
- Returns
Returns omni::core::kResultSuccess upon success, a failure code otherwise.
-
inline bool
isLoggingAtLevel
(const char *name, omni::log::Level level) noexcept¶ Given a channel and a verbosity level, returns
true
if the channel is actively logging at the given level.Using the
OMNI_LOG_*
macros is preferred over this method, as those macros use a much more efficient method to filter messages. However, the mechanics utilized byOMNI_LOG_*
are not viable when binding to languages such as Python, thus this method’s existence.- Thread Safety
This method is thread safe.
-
inline void
flush
() noexcept¶ Flush all queued messages to message consumers.
If asynchronous logging is enabled (see omni::log::ILog::setAsync), blocks until all pending messages have been delivered to message consumers.
- Thread Safety
This method is thread safe.
-
inline void
addChannelUpdateConsumer
(omni::core::ObjectParam<omni::log::ILogChannelUpdateConsumer> consumer) noexcept¶ Adds the given channel updated consumer to the internal list of update consumers.
Each time the state of the log changes, each update consumer is notified.
A consumer can be registered a single time with a given omni::log::ILog instance but can be registered with multple omni::log::ILog instances.
Each message may be sent to registered consumers in parallel.
It is safe to access omni::log::ILog from the callback.
- Thread Safety
This method is thread safe.
-
inline omni::core::ObjectPtr<omni::log::ILogChannelUpdateConsumer>
addChannelUpdateConsumer
(std::function<void(omni::log::ILog *log, omni::str::IReadOnlyCString *name, omni::log::ChannelUpdateReason reason)> fun) noexcept¶ Adds the given channel updated consumer to the internal list of update consumers.
Each time the state of the log changes, each update consumer is notified.
A consumer can be registered a single time with a given omni::log::ILog instance but can be registered with multple omni::log::ILog instances.
Each message may be sent to registered consumers in parallel.
It is safe to access omni::log::ILog from the callback.
- Thread Safety
This method is thread safe.
-
inline void
removeChannelUpdateConsumer
(omni::core::ObjectParam<omni::log::ILogChannelUpdateConsumer> consumer) noexcept¶ Removes the given consumer from the internal consumer list.
This method silently accepts
nullptr
.This method silently accepts consumers that have not been registered with this object.
Calling omni::log::ILog::removeChannelUpdateConsumer() from omni::log::ILogMessageConsumer::onMessage() will lead to undefined behavior.
- Thread Safety
This method is thread safe.
-
inline void *
cast
(omni::core::TypeId id) noexcept¶ Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.
Objects can support multiple interfaces, even interfaces that are in different inheritance chains.
The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.
The returned pointer can be safely
reinterpret_cast<>
to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast toomni::windowing::IWindow
.Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().
- Thread Safety
This method is thread safe.
-
inline void
acquire
() noexcept¶ Increments the object’s reference count.
Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().
Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.
- Thread Safety
This method is thread safe.
-
inline void
release
() noexcept¶ Decrements the objects reference count.
Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).
Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().
Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.
- Thread Safety
This method is thread safe.