Implementation:Rapidsai Cuml C API Handle

Knowledge Sources	Rapidsai_Cuml
Domains	Machine_Learning, GPU_Computing
Last Updated	2026-02-08 12:00 GMT

Overview

Provides the C-language API for creating, configuring, and destroying cuML library handles, along with error types and custom memory allocator support.

Description

This header defines the C-compatible interface for managing cuML handles (cumlHandle_t), which encapsulate the GPU execution context including CUDA streams and memory allocators. The API exposes functions to create and destroy handles, retrieve the associated CUDA stream, set custom device and host memory allocators, and translate error codes into human-readable strings.

The cumlError_t enum defines the possible error states: CUML_SUCCESS, CUML_ERROR_UNKNOWN, and CUML_INVALID_HANDLE. Two function pointer typedefs (cuml_allocate and cuml_deallocate) allow callers to provide custom memory management routines for both device (GPU) and host (CPU) allocations.

This header is explicitly guarded against inclusion from the C++ API (CUML_CPP_API macro). It is intended only for C-API consumers and internal bridge code.

Usage

Use this API when interfacing with cuML from C code or from language bindings that require a C-compatible interface. Create a handle with cumlCreate, optionally configure allocators with cumlSetDeviceAllocator and cumlSetHostAllocator, perform cuML operations, then release resources with cumlDestroy.

Code Reference

Source Location

• Repository: Rapidsai_Cuml
• File: cpp/include/cuml/cuml_api.h

Signature

typedef int cumlHandle_t;

typedef enum cumlError_t {
  CUML_SUCCESS,
  CUML_ERROR_UNKNOWN,
  CUML_INVALID_HANDLE
} cumlError_t;

typedef cudaError_t (*cuml_allocate)(void** p, size_t n, cudaStream_t stream);
typedef cudaError_t (*cuml_deallocate)(void* p, size_t n, cudaStream_t stream);

const char* cumlGetErrorString(cumlError_t error);

cumlError_t cumlCreate(cumlHandle_t* handle, cudaStream_t stream);

cumlError_t cumlGetStream(cumlHandle_t handle, cudaStream_t* stream);

cumlError_t cumlSetDeviceAllocator(cumlHandle_t handle,
                                   cuml_allocate allocate_fn,
                                   cuml_deallocate deallocate_fn);

cumlError_t cumlSetHostAllocator(cumlHandle_t handle,
                                 cuml_allocate allocate_fn,
                                 cuml_deallocate deallocate_fn);

cumlError_t cumlDestroy(cumlHandle_t handle);

Import

#include <cuml/cuml_api.h>

I/O Contract

Inputs

Name	Type	Required	Description
handle	cumlHandle_t* / cumlHandle_t	Yes	Pointer to or value of the cuML handle
stream	cudaStream_t	Yes (for cumlCreate)	CUDA stream to which cuML work is ordered
allocate_fn	cuml_allocate	Yes (for allocator setters)	Function pointer for custom memory allocation
deallocate_fn	cuml_deallocate	Yes (for allocator setters)	Function pointer for custom memory deallocation
error	cumlError_t	Yes (for cumlGetErrorString)	Error code to translate

Outputs

Name	Type	Description
return value	cumlError_t	Status code indicating success or failure
handle (out)	cumlHandle_t*	The created handle (from cumlCreate)
stream (out)	cudaStream_t*	The stream associated with the handle (from cumlGetStream)
error string	const char*	Human-readable error description (from cumlGetErrorString)

Usage Examples

#include <cuml/cuml_api.h>
#include <stdio.h>

// Custom device allocator using cudaMalloc/cudaFree
cudaError_t device_allocate(void** p, size_t n, cudaStream_t stream) {
    return cudaMalloc(p, n);
}

cudaError_t device_deallocate(void* p, size_t n, cudaStream_t stream) {
    return cudaFree(p);
}

int main() {
    cumlHandle_t handle;
    cudaStream_t stream;
    cudaStreamCreate(&stream);

    // Create a cuML handle bound to a CUDA stream
    cumlError_t err = cumlCreate(&handle, stream);
    if (err != CUML_SUCCESS) {
        printf("Error: %s\n", cumlGetErrorString(err));
        return 1;
    }

    // Optionally set a custom device allocator
    cumlSetDeviceAllocator(handle, device_allocate, device_deallocate);

    // ... perform cuML operations using the handle ...

    // Destroy the handle and release resources
    cumlDestroy(handle);
    cudaStreamDestroy(stream);

    return 0;
}

Related Pages

• Environment:Rapidsai_Cuml_CUDA_GPU