# PetscDeviceMemset
Memset device-aware memory 
## Synopsis
```
#include <petscdevice.h> 
PetscErrorCode PetscDeviceMemset(PetscDeviceContext dctx, void *ptr, PetscInt v, std::size_t n)
```
Not Collective, Asynchronous, Auto-dependency aware


## Input Parameters

- ***dctx  -*** The `PetscDeviceContext` used to memset the memory
- ***ptr   -*** The pointer to the memory
- ***v     -*** The value to set
- ***n     -*** The amount (in bytes) to set



## Notes
`ptr` must have been allocated by `PetscDeviceMalloc()` or `PetscDeviceCalloc()`.

The user should prefer `PetscDeviceArrayZero()` over this routine as it automatically
computes the number of bytes to copy from the size of the pointer types, though they should
note that it only zeros memory.

This routine is analogous to `memset()`. That is, this routine copies the value
`static_cast<unsigned char>(v)` into each of the first count characters of the object pointed
to by `dest`.

If `dest` is on device, this routine is asynchronous.


## DAG representation
```none
  time ->

  -> dctx - |= CALL =| - dctx ->
  -> dest --------------------->
```





## 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
 `PetscDeviceArrayZero()`, `PetscDeviceMalloc()`, `PetscDeviceCalloc()`,
`PetscDeviceFree()`

## Level
intermediate

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/objects/device/interface/memory.cxx.html#PetscDeviceMemset">src/sys/objects/device/interface/memory.cxx</A>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/sys/objects/device/interface/memory.cxx)


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