omni::log::ILog¶

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 void setChannelEnabled(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::Result getChannelEnabled(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 void setChannelLevel(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::Result getChannelLevel(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 bool isLoggingAtLevel(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 by OMNI_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). If strCharCount 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 not nullptr, 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 and description must not be nullptr.

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 be nullptr.

If the channel does not have a description set, *outDescription is set to nullptr.

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 by OMNI_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 to omni::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.