ITypeFactory

class omni.core.ITypeFactory

Bases: _ITypeFactory

A mapping from type id’s to implementations.

This object maps type id’s to concrete implementations. The type id’s can represent interface ids or implementation ids.

Register types with registerInterfaceImplementationsFromModule() and registerInterfaceImplementations().

Instantiate types with omni::core::createType(). This is the primary way Omniverse applications are able to instantiate concrete implementations of @rstref{ABI-safe <abi-compatibility>} interfaces. See omni::core::createType() for a helpful wrapper around omni::core::ITypeFactory::createType().

In practice, there will be a single ITypeFactory active in the process space (accessible via omniGetTypeFactoryWithoutAcquire()). However, @ref omni::core::ITypeFactory is not inherently a singleton, and as such multiple instantiations of the interface may exists. This can be used to create private type trees.

Unless otherwise noted, all methods in this interface are thread safe.

Methods

`__init__`(args, *kwargs)	Overloaded function.
`get_type_id_name`(self, id)	Maps a type id back to its type name.
`register_interface_implementations_from_module`(...)	Registers types from the given module.
`set_interface_defaults`(self, interface_id, ...)	Sets the implementation matching constraints for the given interface id.
`unregister_interface_implementations_from_module`(...)	Unregisters all types registered from the given module.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: omni.core._core.ITypeFactory, arg0: omni.core._core.IObject) -> None
__init__(self: omni.core._core.ITypeFactory) -> None

get_type_id_name(self: omni.core._core._ITypeFactory, id: int) → str

Maps a type id back to its type name.

The memory returned is valid for the lifetime of ITypeFactory

Returns nullptr if id has never been registered. Types that have been registered, and then unregistered, will still have a valid string returned from this method.

This method is thread safe.

register_interface_implementations_from_module(self: omni.core._core.ITypeFactory, module_name: str, flags: int) → int

Registers types from the given module.

If the module is currently loaded, it will not be reloaded and kResultSuccess is returned.

Modules (e.g. .dll or .so) may contain one or many implementations of one or many interfaces. When registering a module with the type factory, a function, whose name is described by ‘kModuleGetExportsName’, is found and invoked. Let’s assume the exported function name is “omniModuleGetExports”.

“omniModuleGetExports” returns a key/value database of the module’s capabilities and the module’s requirements. Some things to note about this database:

The module’s requirements can be marked as optional.

The module’s capabilities can be ignored by ITypeFactory.

These properties allow ITypeFactory and the module to find an intersection of desired functionality in a data driven manner. If one party’s required needs are not met, the module fails to load (e.g. an appropriate omni::core::Result is returned).

It is expected the module has entries in the key/value database describing the functions ITypeFactory should call during the loading process. The most important of these entries is the one defined by OMNI_MODULE_ON_MODULE_LOAD(), which points to the function ITypeFactory should call to get a list of implementations in the module. ITypeFactory invokes exports from the module in the following pattern:

.------------------------------------------------------------------------------------------------------------.
|                                               -> Time ->                                                   |
|------------------------------------------------------------------------------------------------------------|
| omniModuleGetExports | onLoad (req.) | onStarted (optional) | onCanUnload (optional) | onUnload (optional) |
|                      |               | impl1->createFn      |                        |                     |
|                      |               | impl2->createFn      |                        |                     |
|                      |               | impl1->createFn      |                        |                     |
\------------------------------------------------------------------------------------------------------------/

Above, functions in the same column can be called concurrently. It’s up to the module to make sure such call patterns are thread safe within the module.

onCanUnload and createFn can be called multiple times. All other functions are called once during the lifecycle of a module.

see omni/core/ModuleExports.h. see onModuleLoadFn see onModuleStartedFn see onModuleCanUnloadFn see onModuleUnloadFn

The module can be explicitly unloaded with unregisterInterfaceImplementationsFromModule().

Upon destruction of this ITypeFactory, unregisterInterfaceImplementationsFromModule is called for each loaded module. If the ITypeFactory destructor’s call to unregisterInterfaceImplementationsFromModule fails to safely unload a module (via the module’s onModuleCanUnload and onModuleUnload), an attempt will be made to forcefully/unsafely unload the module.

The given module name must not be nullptr.

This method is thread safe. Modules can be loaded in parallel.

returns Returns kResultSuccess if the module is loaded (either due to this function or a previous call). Otherwise, an error is returned.

set_interface_defaults(self: omni.core._core.ITypeFactory, interface_id: int, impl_id: int, module_name: str, impl_version: int) → None

Sets the implementation matching constraints for the given interface id.

See omni::core::ITypeFactory_abi::createType_abi() for how these constraints are used.

moduleName can be nullptr.

if implVersion is 0 and implId is an implementation id, the implementation with the highest version is chosen.

This method is thread safe.

unregister_interface_implementations_from_module(self: omni.core._core.ITypeFactory, module_name: str) → int

Unregisters all types registered from the given module.

Unregistering a module may fail if the module does not belief it can safely be unloaded. This is determined by OMNI_MODULE_ON_MODULE_CAN_UNLOAD().

If unregistration does succeed, the given module will be unloaded from the process space.

Upon destruction of this ITypeFactory, unregisterInterfaceImplementationsFromModule is called for each loaded module. If the ITypeFactory destructor’s call to unregisterInterfaceImplementationsFromModule fails to safely unload a module (via the module’s onModuleCanUnload and onModuleUnload), an attempt will be made to forcefully/unsafely unload the module.

The given module name must not be nullptr.

This method is thread safe.

returns Returns kResultSuccess if the module wasn’t already loaded or if this method successfully unloaded the module. Return an error code otherwise.