Skip to navigation

C API

View as Markdown

Source header: cuvs/core/c_api.h

cuVS Error Messages

cuvsError_t

An enum denoting error statuses for function calls

typedef enum {
CUVS_ERROR = 0,
CUVS_SUCCESS = 1
} cuvsError_t;

Values

NameValue
CUVS_ERROR0
CUVS_SUCCESS1

cuvsGetLastErrorText

Returns a string describing the last seen error on this thread, or NULL if the last function succeeded.

const char* cuvsGetLastErrorText();

Returns

const char*

cuvsSetLastErrorText

Sets a string describing an error seen on the thread. Passing NULL clears any previously seen error message.

void cuvsSetLastErrorText(const char* error);

Parameters

NameDirectionTypeDescription
errorconst char*

Returns

void

cuVS Logging

cuvsLogLevel_t

An enum denoting log levels

typedef enum {
CUVS_LOG_LEVEL_TRACE = 0,
CUVS_LOG_LEVEL_DEBUG = 1,
CUVS_LOG_LEVEL_INFO = 2,
CUVS_LOG_LEVEL_WARN = 3,
CUVS_LOG_LEVEL_ERROR = 4,
CUVS_LOG_LEVEL_CRITICAL = 5,
CUVS_LOG_LEVEL_OFF = 6
} cuvsLogLevel_t;

Values

NameValue
CUVS_LOG_LEVEL_TRACE0
CUVS_LOG_LEVEL_DEBUG1
CUVS_LOG_LEVEL_INFO2
CUVS_LOG_LEVEL_WARN3
CUVS_LOG_LEVEL_ERROR4
CUVS_LOG_LEVEL_CRITICAL5
CUVS_LOG_LEVEL_OFF6

cuvsGetLogLevel

Returns the current log level

cuvsLogLevel_t cuvsGetLogLevel();

Returns

cuvsLogLevel_t

cuvsSetLogLevel

Sets the log level

void cuvsSetLogLevel(cuvsLogLevel_t);

Parameters

NameDirectionTypeDescription
arg1cuvsLogLevel_t

Returns

void

cuVS Resources Handle

cuvsResources_t

An opaque C handle for C++ type raft::resources

typedef uintptr_t cuvsResources_t;

cuvsResourcesCreate

Create an Initialized opaque C handle for C++ type raft::resources

cuvsError_t cuvsResourcesCreate(cuvsResources_t* res);

Parameters

NameDirectionTypeDescription
resincuvsResources_t*cuvsResources_t opaque C handle

Returns

cuvsError_t

cuvsResourcesCreateWithMemoryTracking

Create an opaque C handle for C++ type raft::resources whose memory allocations are tracked and written as CSV samples from a background thread.

cuvsError_t cuvsResourcesCreateWithMemoryTracking(cuvsResources_t* res,
const char* csv_path,
int64_t sample_interval_ms);

The returned handle wraps all reachable memory resources (host, pinned, managed, device, workspace, large_workspace) with allocation-tracking adaptors and replaces the global host and device memory resources for the lifetime of the handle. It can be used with single-GPU operations that accept a ::cuvsResources_t, except ::cuvsResourcesSetMemoryPool. The CSV reporter is stopped and the global memory resources are restored when the handle is destroyed via ::cuvsResourcesDestroy.

Parameters

NameDirectionTypeDescription
resoutcuvsResources_t*cuvsResources_t opaque C handle
csv_pathinconst char*Path to the output CSV file (created/truncated). Must be a non-empty, null-terminated UTF-8 string.
sample_interval_msinint64_tMinimum time in milliseconds between successive CSV samples. Pass 10 to match the C++ default.

Returns

cuvsError_t

cuvsResourcesDestroy

Destroy and de-allocate opaque C handle for C++ type raft::resources

cuvsError_t cuvsResourcesDestroy(cuvsResources_t res);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle

Returns

cuvsError_t

cuvsResourcesSetMemoryPool

Set a memory pool on the device used by these resources

cuvsError_t cuvsResourcesSetMemoryPool(cuvsResources_t res,
int percent_of_free_memory);

Call before the handle’s first operation that configures or uses a workspace or large workspace resource. RAFT captures the allocator when either resource is registered, so later device pool changes are rejected. Only handles created by ::cuvsResourcesCreate are supported. Passing a handle created by :cuvsResourcesCreateWithMemoryTracking returns CUVS_ERROR.

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
percent_of_free_memoryinintPercentage of free device memory to allocate for the pool

Returns

cuvsError_t

cuvsResourcesSetStreamPool

Set a CUDA stream pool on these resources

cuvsError_t cuvsResourcesSetStreamPool(cuvsResources_t res, size_t num_streams);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
num_streamsinsize_tNumber of non-blocking CUDA streams in the pool

Returns

cuvsError_t

cuvsStreamSet

Set cudaStream_t on cuvsResources_t to queue CUDA kernels on APIs that accept a cuvsResources_t handle

cuvsError_t cuvsStreamSet(cuvsResources_t res, cudaStream_t stream);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
streamincudaStream_tcudaStream_t stream to queue CUDA kernels

Returns

cuvsError_t

cuvsStreamGet

Get the cudaStream_t from a cuvsResources_t

cuvsError_t cuvsStreamGet(cuvsResources_t res, cudaStream_t* stream);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
streamoutcudaStream_t*cudaStream_t stream to queue CUDA kernels

Returns

cuvsError_t

cuvsStreamSync

Syncs the current CUDA stream on the resources object

cuvsError_t cuvsStreamSync(cuvsResources_t res);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle

Returns

cuvsError_t

cuvsDeviceIdGet

Get the id of the device associated with this cuvsResources_t

cuvsError_t cuvsDeviceIdGet(cuvsResources_t res, int* device_id);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
device_idoutint*int the id of the device associated with res

Returns

cuvsError_t

cuvsResourcesSetWorkspacePool

Configure the temporary workspace on this resources object as an uncapped pool, backed by the current device memory resource. After the initial reservation is allocated on first use, subsequent calls to cuvsRMMAlloc / cuvsRMMFree on the same resources handle hit the pool cache rather than calling cudaMallocAsync / cudaFreeAsync, reducing CUDA context lock contention under concurrent query threads. The pool grows without shrinking: freed allocations are returned to the pool rather than to the device, so the pool’s high-water mark only increases until the resources object is destroyed.

cuvsError_t cuvsResourcesSetWorkspacePool(cuvsResources_t res,
size_t initial_size_bytes);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
initial_size_bytesinsize_tinitial pool reservation in bytes; size to cover the steady-state working set to avoid growth after warmup

Returns

cuvsError_t

cuvsMultiGpuResourcesCreate

Create an Initialized opaque C handle for C++ type raft::device_resources_snmg for multi-GPU operations

cuvsError_t cuvsMultiGpuResourcesCreate(cuvsResources_t* res);

Parameters

NameDirectionTypeDescription
resincuvsResources_t*cuvsResources_t opaque C handle

Returns

cuvsError_t

cuvsMultiGpuResourcesCreateWithDeviceIds

Create an Initialized opaque C handle for C++ type raft::device_resources_snmg for multi-GPU operations with specific device IDs

cuvsError_t cuvsMultiGpuResourcesCreateWithDeviceIds(cuvsResources_t* res,
DLManagedTensor* device_ids);

Parameters

NameDirectionTypeDescription
resincuvsResources_t*cuvsResources_t opaque C handle
device_idsinDLManagedTensor*DLManagedTensor* containing device IDs to use

Returns

cuvsError_t

cuvsMultiGpuResourcesDestroy

Destroy and de-allocate opaque C handle for C++ type raft::device_resources_snmg

cuvsError_t cuvsMultiGpuResourcesDestroy(cuvsResources_t res);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle

Returns

cuvsError_t

cuvsMultiGpuResourcesSetMemoryPool

Set a memory pool on all devices managed by the multi-GPU resources

cuvsError_t cuvsMultiGpuResourcesSetMemoryPool(cuvsResources_t res, int percent_of_free_memory);

Call before the first operation that configures or uses a workspace or large workspace resource on the handle or any managed device. RAFT captures the allocator when either resource is registered, so later pool changes are rejected.

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle for multi-GPU resources
percent_of_free_memoryinintPercent of free memory to allocate for the pool

Returns

cuvsError_t

cuvsMultiGpuResourcesSetStreamPool

Set a CUDA stream pool on all devices managed by the multi-GPU resources

cuvsError_t cuvsMultiGpuResourcesSetStreamPool(cuvsResources_t res,
size_t num_streams);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle for multi-GPU resources
num_streamsinsize_tNumber of CUDA streams in each device’s pool

Returns

cuvsError_t

cuVS Memory Allocation

cuvsRMMAlloc

Allocates device memory using RMM

cuvsError_t cuvsRMMAlloc(cuvsResources_t res, void** ptr, size_t bytes);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
ptroutvoid**Pointer to allocated device memory
bytesinsize_tSize in bytes to allocate

Returns

cuvsError_t

cuvsRMMFree

Deallocates device memory using RMM

cuvsError_t cuvsRMMFree(cuvsResources_t res, void* ptr, size_t bytes);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
ptrinvoid*Pointer to allocated device memory to free
bytesinsize_tSize in bytes to allocate

Returns

cuvsError_t

cuvsRMMPoolMemoryResourceEnable

Switches the working memory resource to use the RMM pool memory resource, which will bypass unnecessary synchronizations by allocating a chunk of device memory up front and carving that up for temporary memory allocations within algorithms. Be aware that this function will change the memory resource for the whole process and the new memory resource will be used until explicitly changed.

cuvsError_t cuvsRMMPoolMemoryResourceEnable(int initial_pool_size_percent,
int max_pool_size_percent,
bool managed);

Parameters

NameDirectionTypeDescription
initial_pool_size_percentinintThe initial pool size as a percentage of the total available memory
max_pool_size_percentinintThe maximum pool size as a percentage of the total available memory
managedinboolWhether to use a managed memory resource as upstream resource or not

Returns

cuvsError_t

cuvsRMMAsyncMemoryResourceEnable

Switches the working memory resource to use stream-ordered asynchronous allocation (cudaMallocAsync / cudaFreeAsync). Unlike the pool resource, this resource returns memory to the stream immediately without blocking the CPU, eliminating device-wide synchronization on deallocation. This is especially beneficial when multiple CAGRA searches run concurrently on separate CUDA streams, because the internal workspace allocations no longer serialize kernel launches. Be aware that this function will change the memory resource for the whole process and the new memory resource will be used until explicitly changed.

cuvsError_t cuvsRMMAsyncMemoryResourceEnable();

Returns

cuvsError_t

cuvsRMMMemoryResourceReset

Resets the memory resource to use the default memory resource (cuda_memory_resource)

cuvsError_t cuvsRMMMemoryResourceReset();

Returns

cuvsError_t

cuvsRMMHostAlloc

Allocates pinned memory on the host using RMM

cuvsError_t cuvsRMMHostAlloc(void** ptr, size_t bytes);

Parameters

NameDirectionTypeDescription
ptroutvoid**Pointer to allocated host memory
bytesinsize_tSize in bytes to allocate

Returns

cuvsError_t

cuvsRMMHostFree

Deallocates pinned memory on the host using RMM

cuvsError_t cuvsRMMHostFree(void* ptr, size_t bytes);

Parameters

NameDirectionTypeDescription
ptrinvoid*Pointer to allocated host memory to free
bytesinsize_tSize in bytes to deallocate

Returns

cuvsError_t

cuvsVersionGet

Get the version of the cuVS library

cuvsError_t cuvsVersionGet(uint16_t* major, uint16_t* minor, uint16_t* patch);

Parameters

NameDirectionTypeDescription
majoroutuint16_t*Major version
minoroutuint16_t*Minor version
patchoutuint16_t*Patch version

Returns

cuvsError_t

cuvsMatrixCopy

Copy a matrix

cuvsError_t cuvsMatrixCopy(cuvsResources_t res, DLManagedTensor* src, DLManagedTensor* dst);

This function copies a matrix from dst to src. This lets you copy a matrix from device memory to host memory (or vice versa), while accounting for differences in strides.

Both src and dst must have the same shape and dtype, but can have different strides and device type. The memory for the output dst tensor must already be allocated and the tensor initialized.

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
srcinDLManagedTensor*Pointer to DLManagedTensor to copy
dstoutDLManagedTensor*Pointer to DLManagedTensor to receive copy of data

Returns

cuvsError_t

cuvsMatrixSliceRows

Slices rows from a matrix

cuvsError_t cuvsMatrixSliceRows(
cuvsResources_t res, DLManagedTensor* src, int64_t start, int64_t end, DLManagedTensor* dst);

Parameters

NameDirectionTypeDescription
resincuvsResources_tcuvsResources_t opaque C handle
srcinDLManagedTensor*Pointer to DLManagedTensor to copy
startinint64_tFirst row index to include in the output
endinint64_tLast row index to include in the output
dstoutDLManagedTensor*Pointer to DLManagedTensor to receive slice from matrix

Returns

cuvsError_t