IStructuredLogControl2_abi#

Fully qualified name: omni::structuredlog::IStructuredLogControl2_abi

Defined in omni/structuredlog/IStructuredLogControl2.h

class IStructuredLogControl2_abi : public omni::core::Inherits<omni::structuredlog::IStructuredLogControl_abi, std::integral_constant<uint64_t, carb::fnv1aHash("omni.structuredlog.IStructuredLogControl2")>::value>#

Interface for the second version of the IStructuredLogControl interface.

This interface exposes more functions to control the behavior of the structured logging system. This object can be retrieved directly or by casting the main IStructuredLog interface to this type using omni::core::ObjectPtr::as<>().

Subclassed by omni::core::Generated< omni::structuredlog::IStructuredLogControl2_abi >

Public Functions

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.

Protected Functions

virtual void emitProcessLifetimeExitEvent_abi(

const char *reason,

) noexcept = 0#

Immediately emits the process lifetime exit event for the process.

Remark

This forces the process lifetime exit event to be emitted early for the process. If this is called, it will pre-empt the normal attempt to emit it automatically when omni.structuredlog.plugin unloads. This can be used to provide a different reason message for the exit event or to explicitly emit the event in situations where omni.structuredlog.plugin cannot be properly unloaded (ie: another system leaks or hangs onto a reference to one of the objects from the library).

Note

This should only ever be called when a process shutdown is iminent and cannot be cancelled or avoided. If this is emitted earlier in the process than exit time, the analysis of the process’ duration could be incorrect.

Note

Calling this will flush the structuredlog queue to ensure the event is flushed to disk before the process exits.

Parameters:

reason – [in] The reason why the exit event is being emitted. This can be any text that gives and indication for why an exit is occurring. This may not be nullptr and should not be an empty string.

Returns:

No return value.

virtual void closeLog_abi(EventId event) noexcept = 0#

Closes one or more schema’s persistently open log file(s).

Remark

This closes the persistently open log file(s) for one or more schemas. This operation will effectively be ignored for schemas that were not registered using the omni::structuredlog::fSchemaFlagKeepLogOpen schema flag since those schemas will not leave their logs open. The named log files will only remain closed until the next attempt to write an event message to it. It is the responsibility of the host app to ensure no events are written to the effected log file(s) for the duration that the log needs to remain closed.

Note

This call itself is thread safe. However the log file may be reopened if a pending event is processed in the event queue or a new event is sent while the calling thread expects the log to remain closed. It is the caller’s responsibility to either stop the event queue, disable structured logging, or prevent other events from being sent while the log(s) need to remain closed.

Parameters:

event – [in] The ID of the event to close the log for. This may also be omni::structuredlog::kAllSchemas to close all log file for the process. The log file for the schema that the given event belongs to will be closed.

Returns:

No return value.

virtual void stop_abi() noexcept = 0#

Stop the structured log event consumer thread.

Remark

This stops the structured log event processing system. This will stop the processing thread and flush all pending event messages to the log. The processing system will be restarted when the next omni::structuredlog::IStructuredLog::allocEvent() call is made to attempt to send a new message. This call is useful if the structured log plugin needs to be unloaded. If the processing thread is left running, it will prevent the plugin from being unloaded (or even being attempted to be unloaded). This can also be used to temporarily disable the structured log system if its not needed or wanted. If the structured log system needs to be disabled completely, a call to omni::structuredlog::IStructuredLog::setEnabled() using the omni::structuredlog::fEnableFlagAll flag should be made before stopping the event queue.

Thread Safety

This call is thread safe.

Returns:

No return value.

virtual void *cast_abi(TypeId id) noexcept = 0#

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.

virtual void acquire_abi() noexcept = 0#

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.

virtual void release_abi() noexcept = 0#

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.