Implementation:NVIDIA DALI C API V2 Error Handling
| Knowledge Sources | |
|---|---|
| Domains | Data_Pipeline, C_API |
| Last Updated | 2026-02-08 16:00 GMT |
Overview
The C API v2 error handling module translates C++ exceptions into thread-local error codes and messages, providing the error reporting infrastructure for all DALI C API v2 functions.
Description
This file implements the error handling subsystem for the DALI C API v2. It belongs to the dali::c_api namespace and provides the mechanism by which C++ exceptions thrown during API execution are captured, classified, and made available to C callers through thread-local storage.
The central component is the HandleError function, which takes a std::exception_ptr and dispatches through a comprehensive chain of catch blocks to map each exception type to the appropriate daliResult_t error code. The mapping covers: InvalidHandle to DALI_ERROR_INVALID_HANDLE, invalid_key to DALI_ERROR_INVALID_KEY, CUDAError to DALI_ERROR_CUDA_ERROR (with special handling for cudaErrorNotReady/CUDA_ERROR_NOT_READY mapped to DALI_NOT_READY), std::bad_alloc to DALI_ERROR_OUT_OF_MEMORY, std::out_of_range, std::invalid_argument, std::system_error (with detailed std::errc classification for I/O, path, and memory errors), std::runtime_error to DALI_ERROR_INVALID_OPERATION, and catch-all for unknown exceptions.
The thread-local ErrorInfo struct stores the last error result code and message string (pre-allocated to 1024 bytes to help report OOM conditions). The public C functions daliGetLastError, daliGetLastErrorMessage, daliClearLastError, daliGetErrorName, and daliGetErrorDescription provide access to the error state. A GetErrorDesc helper maps each daliResult_t value to a human-readable name and description.
Usage
This module is used by every C API v2 function through the DALI_PROLOG() and DALI_EPILOG() macros. After any C API call that returns a non-success daliResult_t, callers should use daliGetLastErrorMessage() to retrieve the detailed error message. Call daliClearLastError() to reset the error state before a new operation.
Code Reference
Source Location
- Repository: NVIDIA_DALI
- File: dali/c_api_2/error_handling.cc
- Lines: 1-198
Signature
namespace dali::c_api {
struct ErrorInfo {
daliResult_t result = DALI_SUCCESS;
std::string message;
};
daliResult_t SetLastError(daliResult_t result, const char *message);
daliResult_t HandleError(std::exception_ptr ex);
ErrorDesc GetErrorDesc(daliResult_t result);
} // namespace dali::c_api
// C API functions
daliResult_t daliGetLastError();
const char *daliGetLastErrorMessage();
void daliClearLastError();
const char *daliGetErrorName(daliResult_t result);
const char *daliGetErrorDescription(daliResult_t result);
Import
#include "dali/c_api_2/error_handling.h"
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| ex | std::exception_ptr | Yes (internal) | Exception captured during C API function execution |
| result | daliResult_t | Yes | Error code to query name or description |
Outputs
| Name | Type | Description |
|---|---|---|
| daliResult_t | enum | Error code: DALI_SUCCESS, DALI_ERROR_INVALID_HANDLE, DALI_ERROR_INVALID_ARGUMENT, DALI_ERROR_CUDA_ERROR, DALI_ERROR_OUT_OF_MEMORY, DALI_ERROR_SYSTEM, etc. |
| error message | const char * | Thread-local detailed error description string |
| error name | const char * | Symbolic name of the error code (e.g., "DALI_ERROR_CUDA_ERROR") |
| error description | const char * | Human-readable description of the error category |
Usage Examples
Checking Errors After API Calls
#include "dali/dali.h"
daliPipeline_h pipeline = nullptr;
daliResult_t result = daliPipelineBuild(pipeline);
if (result != DALI_SUCCESS) {
const char *error_name = daliGetErrorName(result);
const char *error_msg = daliGetLastErrorMessage();
fprintf(stderr, "DALI Error [%s]: %s\n", error_name, error_msg);
daliClearLastError();
}
Error Code to Description Mapping
// daliGetErrorName(DALI_ERROR_INVALID_HANDLE) returns "DALI_ERROR_INVALID_HANDLE"
// daliGetErrorDescription(DALI_ERROR_INVALID_HANDLE) returns
// "The operation received an invalid DALI handle."
// daliGetErrorName(DALI_ERROR_OUT_OF_MEMORY) returns "DALI_ERROR_OUT_OF_MEMORY"
// daliGetErrorDescription(DALI_ERROR_OUT_OF_MEMORY) returns
// "Cannot allocate memory"
// daliGetErrorName(DALI_NOT_READY) returns "DALI_NOT_READY"
// daliGetErrorDescription(DALI_NOT_READY) returns
// "The query succeeded, but the operation queried is still pending."