Implementation:NVIDIA DALI Operator Base Class

Knowledge Sources	NVIDIA DALI
Domains	Custom_Operators, GPU_Computing, Data_Pipeline
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete class template dali::Operator<Backend> and the example NaiveHistogram<Backend> class provided by NVIDIA DALI, demonstrating how to inherit from the operator base class and implement SetupImpl() and RunImpl() to create a custom histogram operator.

Description

The dali::Operator<Backend> template class (defined in dali/pipeline/operator/operator.h) serves as the primary base class for all backend-specific DALI operators. It inherits from OperatorBase, which provides:

• Constructor accepting const OpSpec &spec and extracting num_threads_ and max_batch_size_.
• Public Setup() method that enforces uniform input batch size, checks input layouts, and delegates to the pure virtual SetupImpl().
• Public Run() method that calls RunImpl(), waits for thread pool work, and enforces uniform output batch size.

The NaiveHistogram<Backend> example class (defined in naive_histogram.h) demonstrates the canonical pattern:

• The constructor extracts n_bins from the OpSpec and stores it as n_histogram_bins_.
• SetupImpl() declares a single output with shape [n_histogram_bins_] per sample and DALI_INT32 type.
• RunImpl() is declared but defined in a separate .cu file for GPU specialization.

Usage

To create a custom operator, define a class template inheriting from dali::Operator<Backend>, implement SetupImpl() and RunImpl(), and compile as a shared library plugin.

Code Reference

Source Location

• Repository: NVIDIA DALI
• File (base class): dali/pipeline/operator/operator.h (lines 260-310)
• File (example): docs/examples/custom_operations/custom_operator/naive_histogram/naive_histogram.h (lines 24-68)

Signature

// Base class template
template <typename Backend>
class DLL_PUBLIC Operator : public OperatorBase {
 public:
  using OperatorBase::OperatorBase;
};

// Example custom operator
template<typename Backend>
class NaiveHistogram : public ::dali::Operator<Backend> {
 public:
  explicit NaiveHistogram(const ::dali::OpSpec &spec) :
          ::dali::Operator<Backend>(spec),
          n_histogram_bins_(spec.GetArgument<int>("n_bins")) {}

 protected:
  bool SetupImpl(std::vector<::dali::OutputDesc> &output_desc,
                 const ::dali::Workspace &ws) override;

  void RunImpl(::dali::Workspace &ws) override;

 private:
  int n_histogram_bins_;
};

Import

#include "dali/pipeline/operator/operator.h"
#include "dali/core/tensor_shape.h"

I/O Contract

Inputs

Name	Type	Required	Description
spec	const dali::OpSpec &	Yes	Operator specification containing all arguments, input/output counts, and backend type. Arguments are retrieved via spec.GetArgument<T>("name").
output_desc	std::vector<dali::OutputDesc> &	Yes (SetupImpl)	Mutable vector to be populated with output shapes and types. Each element describes one output.
ws	const dali::Workspace & (SetupImpl) / dali::Workspace & (RunImpl)	Yes	Workspace providing access to input tensors, output tensors, CUDA stream, and thread pool.

Outputs

Name	Type	Description
SetupImpl return	bool	Returns true to indicate that DALI should pre-allocate output buffers based on output_desc.
output_desc[0]	OutputDesc	Shape: uniform_list_shape(batch_size, {n_histogram_bins_}), Type: DALI_INT32. Describes the 1-D histogram output per sample.
ws.Output<Backend>(0)	TensorList<Backend>	Pre-allocated output tensor list written to during RunImpl().

Usage Examples

Example: NaiveHistogram SetupImpl

bool SetupImpl(std::vector<::dali::OutputDesc> &output_desc,
               const ::dali::Workspace &ws) override {
  using namespace ::dali;
  const auto &input = ws.Input<Backend>(0);

  // Declare one output
  output_desc.resize(1);

  // Each sample is a 1-D vector of n_histogram_bins_ int32 values
  output_desc[0] = {uniform_list_shape(input.num_samples(), {n_histogram_bins_}), DALI_INT32};
  return true;
}

Example: Constructor with argument extraction

explicit NaiveHistogram(const ::dali::OpSpec &spec) :
        ::dali::Operator<Backend>(spec),
        n_histogram_bins_(spec.GetArgument<int>("n_bins")) {}

Related Pages

Implements Principle

• Principle:NVIDIA_DALI_Custom_Operator_Class_Definition

Requires Environment

• Environment:NVIDIA_DALI_CMake_Build_Environment