omni::structuredlog::IStructuredLogControl_abi

Defined in omni/structuredlog/IStructuredLogControl.h

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

Structured log state control interface.

This allows for some control over the processing of events and log files for the structured log system. The structured log system’s event queue can be temporarily stopped if needed or the output log for a schema may be closed. Each of these operations is only temporary as the event queue will be restarted and the log file opened when the next event is queued with omni::structuredlog::IStructuredLog::allocEvent().

This interface object can be acquired either by requesting it from the type factory or by casting an omni::structuredlog::IStructuredLog object to this type.

Subclassed by omni::core::Generated< omni::structuredlog::IStructuredLogControl_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 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.