Memory

The memory object abstracts memory allocated in a device. It facilitates data transfer between host and device, as well as device to device.

When using the unified memory option, OCCA automatically copies data between host/device. Enough control is given to prevent automatic data transfer by specifying whether data in a kernel was/wasn’t modified.

Constructors/Destructors

Constructors

occa::memory occa::memory::operator + (
const dim_t offset
)

Creates a occa::memory reference with a byte offset. No new memory is allocated.

Parameters:

  • offset  -  

    Byte offset applied to the returned occa::memory object

occa::memory all = device.malloc(10 * sizeof(int));

occa::memory left  = all;
occa::memory right = all + (5 * sizeof(int));
occa::memory m1, m2;
...
m1.copyFrom(m2 + (10 * sizeof(int)));
New in version 1.0
occa::memory& occa::memory::operator += (
const dim_t offset
)

Applies a byte offset

Parameters:

  • offset  -  

    Byte offset applied to the returned occa::memory object

occa::memory m = device.malloc(N * sizeof(int));
occa::memory mPart = m;
for (int i = 0; i < 100; ++i) {
  mPart += (N / 100) * sizeof(int);
  kernel(100, mPart);
}
New in version 1.0

Destructors

void occa::memory::free ()

Frees

  • The occa::memory object
  • The memory allocated in the device
  • The backend memory handle
occa::memory mem = device.malloc(10 * sizeof(int));
...
mem.free();
New in version 1.0
void occa::memory::detach ()

Unlike free(), detach doesn’t free the memory allocated. This is useful when wrapping existing memory objects allocated in other code or libraries.

Frees

  • The occa::memory object
  • The backend memory handle
occa::device device("mode: 'Serial'");
int *ptr = new int[10];
occa::memory mem = device.wrapMemory(ptr, 10 * sizeof(int));
...
mem.detach();
New in version 1.0

Memory Information

bool occa::memory::isInitialized () const

Returns true if the memory has been allocated by a device and not freed.

occa::memory mem;
std::cout << "Memory initialized: " << mem.isInitialized() << '\n';
mem = device.malloc(10 * sizeof(int));
std::cout << "Memory initialized: " << mem.isInitialized() << '\n';
New in version 1.0
occa::device occa::memory::getDevice () const

Returns the occa::device that allocated the memory object. If the memory has not been allocated, the returned device.isInitialized() will return false

mem = device.malloc(10 * sizeof(int));
...
occa::device memDevice = mem.getDevice();
New in version 1.0
const std::string& occa::memory::mode () const

Returns the mode of the device used to allocate the memory object. The mode can also be obtained through its properties.

occa::device device("mode: 'Serial'");
occa::memory mem = device.malloc(10 * sizeof(int));
std::cout << "The device mode is: " << mem.mode() << '\n';
New in version 1.0
udim_t occa::memory::size () const

Returns the bytes allocated for the memory object. Returns 0 if the memory object has not been initialized.

occa::memory mem = device.malloc(10 * sizeof(int));
std::cout << "Bytes allocated: " << mem.size() << '\n';
New in version 1.0
udim_t occa::memory::size ()

Returns the number of entries (type TM) allocated for the memory object. Returns 0 if the memory object has not been initialized.

occa::memory mem = device.malloc(10 * sizeof(int));
std::cout << "Ints allocated: " << mem.size<int>() << '\n';
New in version 1.0

Data Movement

void occa::memory::swap (
occa::memory &m
)

Swaps underlying memory objects with m

Parameters:

  • m  -  

    Memory object that will be swapped

occa::memory a;
occa::memory b;
...
a.swap(b);
New in version 1.0

Copying To Device

void occa::memory::copyTo (
void *dest,
const dim_t bytes = -1,
const dim_t offset = 0,
const occa::properties &props = occa::properties()
) const

Copies data in the memory object to either a host pointer or unified memory pointer in the device

Parameters:

  • dest  -  

    Destination where the data will be copied to

  • bytes  -  

    Bytes of data that will be copied

  • offset  -  

    Offset to the memory object where data copying begins

  • props  -  

    Information used for memory transfer which could be device-dependent

int *a = new int[10];
occa::memory m = device.malloc(10 * sizeof(int));
...
m.copyTo(a);
int *a = new int[10];
occa::memory m = device.malloc(15 * sizeof(int));
...
m.copyTo(a, 10 * sizeof(int), 5 * sizeof(int));
New in version 1.0
void occa::memory::copyTo (
void *dest,
const occa::properties &props
) const

Copies data in the memory object to either a host pointer or unified memory pointer in the device

Parameters:

  • dest  -  

    Destination where the data will be copied to

  • props  -  

    Information used for memory transfer which could be device-dependent

int *a = new int[10];
occa::memory m = device.malloc(10 * sizeof(int));
...
m.copyTo(a);
New in version 1.0
void occa::memory::copyTo (
const memory dest,
const dim_t bytes = -1,
const dim_t destOffset = 0,
const dim_t srcOffset = 0,
const occa::properties &props = occa::properties()
) const

Copies data in the memory object to either a host pointer or unified memory pointer in the device

Parameters:

  • dest  -  

    Destination where the data will be copied to

  • bytes  -  

    Bytes of data that will be copied

  • destOffset  -  

    Offset to the destination memory object where data copying begins

  • srcOffset  -  

    Offset to the source memory object where data copying begins

  • props  -  

    Information used for memory transfer which could be device-dependent

occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(10 * sizeof(int));
...
a.copyTo(b);
occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(15 * sizeof(int));
...
a.copyTo(b, 10 * sizeof(int), 5 * sizeof(int));
New in version 1.0
void occa::memory::copyTo (
const memory dest,
const occa::properties &props
) const

Copies data in the memory object to either a host pointer or unified memory pointer in the device

Parameters:

  • dest  -  

    Destination where the data will be copied to

  • props  -  

    Information used for memory transfer which could be device-dependent

occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(10 * sizeof(int));
...
a.copyTo(b);
New in version 1.0

Copying From Device

void occa::memory::copyFrom (
void *src,
const dim_t bytes = -1,
const dim_t offset = 0,
const occa::properties &props = occa::properties()
) const

Copies data from either a host pointer or unified memory pointer in the device to the memory object

Parameters:

  • src  -  

    Source where the data will be copied from

  • bytes  -  

    Bytes of data that will be copied

  • offset  -  

    Offset to the memory object where data copying begins

  • props  -  

    Information used for memory transfer which could be device-dependent

int *a = new int[10];
occa::memory m = device.malloc(10 * sizeof(int));
...
m.copyFrom(a);
int *a = new int[10];
occa::memory m = device.malloc(15 * sizeof(int));
...
m.copyFrom(a, 10 * sizeof(int), 5 * sizeof(int));
New in version 1.0
void occa::memory::copyFrom (
void *src,
const occa::properties &props
) const

Copies data from either a host pointer or unified memory pointer in the device to the memory object

Parameters:

  • src  -  

    Source where the data will be copied from

  • props  -  

    Information used for memory transfer which could be device-dependent

int *a = new int[10];
occa::memory m = device.malloc(10 * sizeof(int));
...
m.copyFrom(a);
New in version 1.0
void occa::memory::copyFrom (
const memory src,
const dim_t bytes = -1,
const dim_t destOffset = 0,
const dim_t srcOffset = 0,
const occa::properties &props = occa::properties()
) const

Copies data from either a host pointer or unified memory pointer in the device to the memory object

Parameters:

  • src  -  

    Source where the data will be copied from

  • bytes  -  

    Bytes of data that will be copied

  • destOffset  -  

    Offset to the destination memory object where data copying begins

  • srcOffset  -  

    Offset to the source memory object where data copying begins

  • props  -  

    Information used for memory transfer which could be device-dependent

occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(10 * sizeof(int));
...
a.copyFrom(b);
occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(15 * sizeof(int));
...
a.copyFrom(b, 10 * sizeof(int), 5 * sizeof(int));
New in version 1.0
void occa::memory::copyFrom (
const memory src,
const occa::properties &props
) const

Copies data from either a host pointer or unified memory pointer in the device to the memory object

Parameters:

  • src  -  

    Source where the data will be copied from

  • props  -  

    Information used for memory transfer which could be device-dependent

occa::memory a = device.malloc(10 * sizeof(int));
occa::memory b = device.malloc(10 * sizeof(int));
...
a.copyFrom(b);
New in version 1.0

Interoperability

void* occa::memory::getHandle (
const occa::properties &props = occa::properties()
) const

Returns a memory handle used by the occa:memory. The return format is dependent on the backend and props.

Parameters:

  • props  -  

    Additional information that might be needed to get specific handle objects from the backend

occa::device device("mode: 'CUDA', deviceID: 0");
occa::memory m = device.malloc(10 * sizeof(int));
int *ptr = (int*) m.getHandle();
New in version 1.0