Allocate device-aware memory


#include <petscdevice.h>
PetscErrorCode PetscDeviceMalloc(PetscDeviceContext dctx, PetscMemType mtype, size_t n, Type **ptr)

Not Collective, Asynchronous, Auto-dependency aware

Input Parameters#

  • dctx - The PetscDeviceContext used to allocate the memory

  • mtype - The type of memory to allocate

  • n - The amount (in elements) to allocate

Output Parameter#

  • ptr - The pointer to store the result in


Memory allocated with this function must be freed with PetscDeviceFree().

If n is zero, then ptr is set to PETSC_NULLPTR.

This routine falls back to using PetscMalloc1() if PETSc was not configured with device support. The user should note that mtype is ignored in this case, as PetscMalloc1() allocates only host memory.

This routine uses the sizeof() of the memory type requested to determine the total memory to be allocated, therefore you should not multiply the number of elements requested by the sizeof() the type:

  PetscInt *arr;

  // correct

  // incorrect

Note result stored ptr is immediately valid and the user may freely inspect or manipulate its value on function return, i.e.:

  PetscInt *ptr;

  PetscDeviceMalloc(dctx, PETSC_MEMTYPE_DEVICE, 20, &ptr);

  PetscInt *sub_ptr = ptr + 10; // OK, no need to synchronize

  ptr[0] = 10; // ERROR, directly accessing contents of ptr is undefined until synchronization

DAG representation#

  time ->

  -> dctx - |= CALL =| -\- dctx -->
                         \- ptr ->

Asynchronous API Notes#

This routine is explicitly marked as exhibiting asynchronous behavior. Asynchronous behavior implies that routines launching operations on (or associated with) a PetscDeviceContext may return to the caller before the operation has completed.

Sequential Consistency:

Operations using the same PetscDeviceContext which access objects or memory regions are ordered per the language specification.

Operations using separate PetscDeviceContexts which access the same object or memory region are strongly write-ordered. That is, the following operations:

  • write-write

  • write-read

  • read-write

are strongly ordered. Formally:

Given an operation A-B (e.g. A = write, B = read) on an object or memory region M such that A “happens-before” B, where A uses PetscDeviceContext X and B uses PetscDeviceContext Y, then B shall not begin before A completes. This implies that any side-effects resulting from A are also observed by B.

Note the omission of read-read; there is no implied ordering between separate PetscDeviceContexts for consecutive reads.

Operations using separate PetscDeviceContexts which access separate objects or memory regions may execute in an arbitrary order and offer no guarantee of sequential consistency.

Memory Consistency:

If this routine modifies the participating object(s) then – unless otherwise stated – the contents of any externally held references to internal data structures should be considered to be in an undefined state. A well-defined state can only be restored by re-acquiring these references through the appropriate API or by calling PetscDeviceContextSynchronize().

Unless otherwise stated, exceptions to this rule are:

  • References returned by the routine itself. If a routine returns a pointer, the value of the top-most pointer is guaranteed to always be valid. For example, given a routine which asynchronously allocates memory and returns a pointer to the memory, the value of said pointer is immediately valid but dereferencing the pointer may not be.

  • References to structures. If a routine returns a PetscFoo, or array thereof then the objects themselves are always valid (though their member variables PetscFoo->data may not be).

See Also#

PetscDeviceFree(), PetscDeviceCalloc(), PetscDeviceArrayCopy(), PetscDeviceArrayZero()





Edit on GitLab

Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages