Principle:NVIDIA DALI Plugin Loading
| Knowledge Sources | |
|---|---|
| Domains | Custom_Operators, Plugin_Architecture, Dynamic_Loading |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Plugin loading is the mechanism by which a compiled custom operator shared library is dynamically loaded into the DALI runtime via nvidia.dali.plugin_manager.load_library(), triggering static initializers that register the operator's schema and factory entry so it becomes available as fn.operator_name() in pipeline definitions.
Description
Plugin loading is the runtime step that bridges compiled C++ operator code with the Python DALI API. The process works as follows:
- Python Entry Point: The user calls nvidia.dali.plugin_manager.load_library("path/to/lib.so") from Python. This is a thin wrapper around the C++ PluginManager::LoadLibrary() method.
- dlopen(): The C++ PluginManager::LoadLibrary() method calls POSIX dlopen() with RTLD_LAZY | RTLD_LOCAL flags (or RTLD_GLOBAL if global_symbols=True). The RTLD_LAZY flag defers symbol resolution until first use, speeding up load time. The RTLD_LOCAL flag (default) keeps the plugin's symbols private, preventing conflicts with other plugins.
- Static Initializer Execution: When dlopen() loads the shared library, the C++ runtime executes all static initializers in the library. This includes the DALI_SCHEMA and DALI_REGISTER_OPERATOR macro expansions, which register the operator's schema in the global SchemaRegistry and its factory function in the device-specific operator registry.
- Operator Availability: After load_library() returns, the operator is discoverable by name. DALI's Python layer generates fn.operator_name() functions dynamically from the schema registry, making the custom operator immediately usable in @pipeline_def functions with the same syntax as built-in operators.
- Default Plugin Loading: DALI also supports automatic plugin loading via PluginManager::LoadDefaultPlugins(), which loads all libdali_*.so files from a default plugin directory (or a custom path set via the DALI_PRELOAD_PLUGINS environment variable).
Usage
Use plugin_manager.load_library() after building a custom operator shared library and before defining any pipeline that uses the operator. This is typically done at module import time or at the top of a script, ensuring the operator is registered before the pipeline graph is constructed.
Theoretical Basis
Plugin loading implements the Dynamic Plugin architectural pattern, where functionality is extended at runtime without modifying or relinking the host application. This pattern relies on the operating system's dynamic linker (dlopen on Linux) to load code into the process address space.
The key enabler is static initialization side effects: the DALI registration macros define static variables whose constructors perform registration. The C++ standard guarantees that static initializers in a shared library execute when the library is loaded with dlopen(). This eliminates the need for an explicit registration API -- the mere act of loading the library is sufficient to register all operators it contains.
The RTLD_LAZY flag implements lazy binding, a performance optimization where function symbols are resolved on first call rather than at load time. This is safe for DALI plugins because all operator symbols are resolved through the factory mechanism (which uses the registry) rather than through direct symbol references.
The RTLD_LOCAL vs RTLD_GLOBAL choice implements symbol visibility control. RTLD_LOCAL (the default) prevents the plugin's symbols from polluting the global symbol namespace, which is important when multiple plugins may define identically-named internal functions. RTLD_GLOBAL is available for cases where plugins need to share symbols.