omni::kit::exec::core::unstable::IExecutionControllerFactory_abi

Defined in omni/kit/exec/core/unstable/IExecutionControllerFactory.h

class IExecutionControllerFactory_abi : public omni::core::Inherits<graph::exec::unstable::IBase, OMNI_TYPE_ID("omni.kit.exec.core.unstable.IExecutionControllerFactory")>

Factory for creating instances of omni::kit::exec::core::unstable::IExecutionController.

This interface also stores the “default” omni::kit::exec::core::unstable::IExecutionController, which is associated with Kit’s “default” UsdContext.

The factory is a singleton. Access the singleton with omni::kit::exec::core::unstable::getExecutionControllerFactory().

Subclassed by omni::core::Generated< omni::kit::exec::core::unstable::IExecutionControllerFactory_abi >

Public Functions

inline void *castWithoutAcquire(omni::core::TypeId id) noexcept

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety

This method is thread safe.

inline uint32_t getUseCount() noexcept

Returns the number of different instances (this included) referencing the current object.

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.

Protected Functions

virtual IExecutionController *createExecutionController_abi(const char *name, omni::usd::IUsdMutex *const usdMutex) noexcept = 0

Creates an omni::kit::exec::core::unstable::IExecutionController.

The given name should match the name of the UsdContext.

The USD mutex should match the mutex of the UsdContext.

The returned controller will have omni::core::IObject::acquire() called on it.

name must not be nullptr.

Thread Safety

This method is not thread safe.

virtual void setDefaultExecutionController_abi(IExecutionController *controller) noexcept = 0

Sets the “default” omni::kit::exec::core::unstable::IExecutionController which should be owned by Kit’s “default” UsdContext.

The given controller must not be nullptr.

This method must not be called if a default controller has already been set.

Thread Safety

This method is not thread safe.

virtual IExecutionController *getDefaultExecutionController_abi() noexcept = 0

Returns the “default” omni::kit::exec::core::unstable::IExecutionController associated with the “default” UsdContext.

The returned pointer may be nullptr.

Prefer calling getDefaultExecutionController() rather than directly calling this method.

The returned controller will have omni::core::IObject::acquire() called on it.

Thread Safety

This method is thread safe.

virtual void clear_abi(const uint64_t moduleHash) noexcept = 0

Attempts to release references to all objects when unloading DLLs.

State managed by controllers may store references to objects emanating from many DLLs. As long as a controller stores a reference to an object, it will not be destructed. This causes a problem when unloading DLLs. If a controller’s graph/context stores a reference to an object created by “foo.dll” and “foo.dll” is unloaded, when the controller later releases its reference to the object, the object’s release() method will call into unloaded code, causing a crash.

The fix for this disastrous scenario is ensure that no outstanding references to objects created in “foo.dll” are present in the process. This method attempts to do just that by releasing all references stored within all controllers/graphs/contexts.

A plugin may choose to store references to execution framework objects originating from other modules. In such a case, the plugin can be notified when this clear() method is called by invoking omni::kit::exec::core::unstable::addClearCallback() when the plugin/module is loaded.

Upon completion of this method, pointers to controllers created by this factory will remain valid, though references within the controllers to objects potentially created by other DLLs will have been released.

The moduleHash is an implementation detail that aids in achieving more granular object cleanup based on the .dll/.so that’s getting unloaded.

Thread Safety

This method is not thread safe and should be called by a single thread at a time.

virtual void addClearCallback_abi(IClearCallback *callback) noexcept = 0

Adds a callback that will be invoked when omni::kit::exec::core::unstable::IExecutionControllerFactory::clear() is called.

omni::kit::exec::core::unstable::IExecutionControllerFactory::clear() is called when a .dll/.so providing execution framework functionality is unloaded (e.g. a plugin that provides a pass or node definition). The purpose of the given callback is to provide the plugin calling this method an opportunity to remove pointers to code that may be unloaded. For example, OmniGraph uses this callback to remove any omni::graph::exec::unstable::IDef pointers in its plugins.

Do not call this method directly. Rather, call OMNI_KIT_EXEC_CORE_ON_MODULE_STARTED in either a plugin’s carbOnPluginStartup or onStarted.

The given callback must not be nullptr.

Thread Safety

This method is not thread safe.

virtual void removeClearCallback_abi(IClearCallback *callback) noexcept = 0

Removes a callback registered with omni::kit::exec::core::unstable::IExecutionControllerFactory::addClearCallback.

If callback is nullptr or was not registered, this function silently fails.

This method should not be explicitly called, rather call OMNI_KIT_EXEC_CORE_ON_MODULE_UNLOAD during plugin/module shutdown.

Thread Safety

This method is not thread safe.

virtual const uint64_t _generateUniqueHash_abi() noexcept = 0

Generate a unique number that’s tied to the factory singleton instance.

Used as an implementation detail to identify modules (i.e. .dll/.so) that utilize the kit-EF integration layer.

This method is not meant to be called explicitly by users.

virtual void *castWithoutAcquire_abi(omni::core::TypeId id) noexcept = 0

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety

This method is thread safe.

virtual uint32_t getUseCount_abi() noexcept = 0

Returns the number of different instances (this included) referencing the current object.

Thread Safety

This method is thread safe.

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.