Principle:NVIDIA DALI Operator Schema Registration
| Knowledge Sources | |
|---|---|
| Domains | Custom_Operators, Operator_Registry, API_Design |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Operator schema registration is the process of declaring an operator's metadata (name, documentation, arguments, input/output counts) and binding it to a concrete implementation class in DALI's global operator registry, using the DALI_SCHEMA and DALI_REGISTER_OPERATOR macros.
Description
Operator schema registration bridges the gap between a C++ operator class and the DALI pipeline's ability to discover, configure, and instantiate that operator by name. The process has two complementary steps:
- Schema Declaration (DALI_SCHEMA): The DALI_SCHEMA(OpName) macro creates an OpSchema object and registers it in a global SchemaRegistry. The schema is populated using a fluent builder API:
- .DocStr("...") -- Sets the operator's documentation string, which is exposed to Python users.
- .AddOptionalArg("name", "description", default_value) -- Declares an optional argument with a name, description, and default value. DALI supports AddArg for required arguments and AddOptionalArg for optional ones, with type inferred from the default value.
- .NumInput(n) -- Declares the number of input tensor arguments.
- .NumOutput(n) -- Declares the number of output tensor arguments.
- Additional methods such as .AddOptionalTypeArg(...), .AllowSequences(), and .InputDevice(...) provide further configurability.
- Operator Registration (DALI_REGISTER_OPERATOR): The DALI_REGISTER_OPERATOR(OpName, OpType, device) macro binds the concrete operator class (e.g., NaiveHistogram<GPUBackend>) to the schema name for a specific device backend. This populates the operator factory so that InstantiateOperator(spec) can construct the correct class at runtime. The macro also enforces that a schema exists for the operator via a compile-time check.
Both macros must be invoked in a .cc (or .cu) file, not in a header, because they rely on static initialization to register entries in global maps.
Usage
Use schema registration for every custom operator. Without it, the operator class cannot be discovered by the pipeline, arguments cannot be validated, and the Python API (fn.operator_name) will not be generated. The schema serves as the single source of truth for the operator's public contract.
Theoretical Basis
Schema registration implements the Self-Registration pattern (a variant of the Factory pattern). Each operator registers itself at static initialization time, eliminating the need for a centralized list of all operators. This is essential for a plugin architecture where operators may be loaded dynamically from shared libraries at runtime.
The fluent builder API on OpSchema implements the Builder pattern, allowing incremental construction of the schema with compile-time type safety for argument defaults. The separation of schema (metadata) from implementation (class) follows the Metadata-Driven Architecture principle, where the schema drives argument validation, Python binding generation, and documentation extraction without coupling to the operator's runtime logic.
The DALI_REGISTER_OPERATOR macro leverages C++ static initialization ordering guarantees within a single translation unit. The macro first references the schema's existence via DALI_OPERATOR_SCHEMA_REQUIRED_FOR_##OpName(), creating a compile-time dependency that ensures the schema is defined before the operator factory entry.