A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Functions
allocV2
ArrayFire Functions | ArrayFire Functions by Category » Functions to create and modify Arrays » Managing devices in ArrayFire

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.
AFAPI af_err | af_alloc_device_v2 (void **ptr, const dim_t bytes)
| Allocates memory using ArrayFire's memory manager.
AFAPI void * | alloc (const size_t elements, const dtype type)
| Allocates memory using ArrayFire's memory manager.
AFAPI void * | allocV2 (const size_t bytes)
| Allocates memory using ArrayFire's memory manager.
template<typename T >
T * | alloc (const size_t elements)
| Allocates memory using ArrayFire's memory manager.

## 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);

## 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);

## 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] | ptr | Pointer 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] | bytes | The 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] | ptr | Pointer 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] | bytes | The 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]

template<typename T >

T * alloc | ( | const size_t | elements | ) |

Allocates memory using ArrayFire's memory manager.

Parameters

  [in] | elements | the 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] | elements | the number of elements to allocate
  [in] | type | is 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] | bytes | the 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