A high-performance general-purpose compute library

Allocate memory using the ArrayFire memory manager. More...

Functions

AFAPI af_err af_alloc_device (void **ptr, const dim_t bytes)
 Allocates memory using ArrayFire's memory manager. More...
 
AFAPI af_err af_alloc_device_v2 (void **ptr, const dim_t bytes)
 Allocates memory using ArrayFire's memory manager. More...
 
AFAPI void * alloc (const size_t elements, const dtype type)
 Allocates memory using ArrayFire's memory manager. More...
 
AFAPI void * allocV2 (const size_t bytes)
 Allocates memory using ArrayFire's memory manager. More...
 
template<typename T >
T * alloc (const size_t elements)
 Allocates memory using ArrayFire's memory manager. More...
 

Detailed Description

Allocate memory using the ArrayFire memory manager.

This function will allocate memory on the device and return a pointer to it. The memory is allocated using ArrayFire's memory manager which will defer releasing memory to the driver and reuse the same memory for later operations.

This function will return different objects based on the type used. The interface returns a void pointer that needs to be cast to the backend appropriate memory type.

function CPU CUDA OpenCL
af_alloc_device_v2 T* T* cl_mem
af::allocV2 T* T* cl_mem
af_alloc_device (deprecated) T* T* cl::Buffer*
af::alloc (deprecated) T* T* cl::Buffer*

CPU Backend

// Allocate one float and cast to float*
void *ptr = af::allocV2(sizeof(float));
float *dptr = static_cast<float *>(ptr);
// This is the CPU backend so we can assign to the pointer
dptr[0] = 5.0f;
freeV2(ptr);
AFAPI void * allocV2(const size_t bytes)
Allocates memory using ArrayFire's memory manager.

CUDA Backend

void *ptr = allocV2(sizeof(float));
float *dptr = static_cast<float *>(ptr);
float host_data = 5.0f;
cudaError_t error = cudaSuccess;
error = cudaMemcpy(dptr, &host_data, sizeof(float), cudaMemcpyHostToDevice);
freeV2(ptr);

OpenCL Backend

cl_command_queue queue;
afcl_get_queue(&queue, true);
cl_context context;
afcl_get_context(&context, true);
void *alloc_ptr = allocV2(sizeof(float));
cl_mem mem = static_cast<cl_mem>(alloc_ptr);
// Map memory from the device to the System memory
cl_int map_err_code;
void *mapped_ptr = clEnqueueMapBuffer(
queue, // command queueu
mem, // buffer
CL_TRUE, // is blocking
CL_MAP_READ | CL_MAP_WRITE, // map type
0, // offset
sizeof(float), // size
0, // num_events_in_wait_list
nullptr, // event_wait_list
nullptr, // event
&map_err_code); // error code
float *float_ptr = static_cast<float *>(mapped_ptr);
float_ptr[0] = 5.0f;
// Unmap buffer after we are done using it
cl_int unmap_err_code =
clEnqueueUnmapMemObject(queue, // command queue
mem, // buffer
mapped_ptr, // mapped pointer
0, // num_events_in_wait_list
nullptr, // event_wait_list
nullptr); // event
freeV2(alloc_ptr);
AFAPI af_err afcl_get_queue(cl_command_queue *queue, const bool retain)
Get a handle to ArrayFire's OpenCL command queue.
AFAPI af_err afcl_get_context(cl_context *ctx, const bool retain)
Get a handle to ArrayFire's OpenCL context.

Function Documentation

◆ af_alloc_device()

AFAPI af_err af_alloc_device ( void **  ptr,
const dim_t  bytes 
)

Allocates memory using ArrayFire's memory manager.

This device memory returned by this function can only be freed using af_free_device

Parameters
[out]ptrPointer to the device memory on the current device. This is a CUDA device pointer for the CUDA backend. A cl::Buffer pointer on the OpenCL backend and a C pointer for the CPU backend
[in]bytesThe number of bites to allocate on the device
Returns
AF_SUCCESS if a pointer could be allocated. AF_ERR_NO_MEM if there is no memory
Deprecated:
Use af_alloc_device_v2 instead. af_alloc_device_v2 returns a cl_mem object instead of the cl::Buffer object for the OpenCL backend. Otherwise the functionallity is identical

◆ af_alloc_device_v2()

AFAPI af_err af_alloc_device_v2 ( void **  ptr,
const dim_t  bytes 
)

Allocates memory using ArrayFire's memory manager.

This device memory returned by this function can only be freed using af_free_device_v2.

Parameters
[out]ptrPointer to the device memory on the current device. This is a CUDA device pointer for the CUDA backend. A cl::Buffer pointer on the OpenCL backend and a C pointer for the CPU backend
[in]bytesThe number of bites to allocate on the device
Returns
AF_SUCCESS if a pointer could be allocated. AF_ERR_NO_MEM if there is no memory

◆ alloc() [1/2]

T * alloc ( const size_t  elements)

Allocates memory using ArrayFire's memory manager.

Parameters
[in]elementsthe number of elements to allocate
Returns
Pointer to the device memory on the current device. This is a CUDA device pointer for the CUDA backend. A cl::Buffer pointer from the cl2.hpp header on the OpenCL backend and a C pointer for the CPU backend
Note
the size of the memory allocated is the number of elements * sizeof(type)
The device memory returned by this function is only freed if af::free() is called explicitly
Deprecated:
Use allocV2 instead. allocV2 accepts number of bytes instead of number of elements and returns a cl_mem object instead of the cl::Buffer object for the OpenCL backend. Otherwise the functionallity is identical to af::alloc.

◆ alloc() [2/2]

AFAPI void * alloc ( const size_t  elements,
const dtype  type 
)

Allocates memory using ArrayFire's memory manager.

Parameters
[in]elementsthe number of elements to allocate
[in]typeis the type of the elements to allocate
Returns
Pointer to the device memory on the current device. This is a CUDA device pointer for the CUDA backend. A cl::Buffer pointer from the cl2.hpp header on the OpenCL backend and a C pointer for the CPU backend
Note
The device memory returned by this function is only freed if af::free() is called explicitly
Deprecated:
Use allocV2 instead. allocV2 accepts number of bytes instead of number of elements and returns a cl_mem object instead of the cl::Buffer object for the OpenCL backend. Otherwise the functionallity is identical to af::alloc.

◆ allocV2()

AFAPI void * allocV2 ( const size_t  bytes)

Allocates memory using ArrayFire's memory manager.

Parameters
[in]bytesthe number of bytes to allocate
Returns
Pointer to the device memory on the current device. This is a CUDA device pointer for the CUDA backend. A cl_mem pointer on the OpenCL backend and a C pointer for the CPU backend
Note
The device memory returned by this function is only freed if af::freeV2() is called explicitly