:orphan:
# 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:

```none
  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.:

```none
  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
```none
  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
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/include/petscdevice.h.html#PetscDeviceMalloc">include/petscdevice.h</A>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/include/petscdevice.h)


[Index of all Sys routines](index.md)  
[Table of Contents for all manual pages](/manualpages/index.md)  
[Index of all manual pages](/manualpages/singleindex.md)