Skip to main content
`Ctrl`+`K`

# PetscDeviceMalloc

Allocate device-aware memory

## Synopsis

    #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

## Notes

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
      PetscDeviceMalloc(dctx,PETSC_MEMTYPE_DEVICE,n,&arr);

      // incorrect
      PetscDeviceMalloc(dctx,PETSC_MEMTYPE_DEVICE,n*sizeof(*arr),&arr);

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 `PetscDeviceContext`s 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 `PetscDeviceContext`s for consecutive reads.

Operations using separate `PetscDeviceContext`s 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()`

## Level

beginner

## Location

include/petscdevice.h

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