PetscDeviceArrayCopy#
Copy memory in a device-aware manner
Synopsis#
#include <petscdevice.h>
PetscErrorCode PetscDeviceArrayCopy(PetscDeviceContext dctx, void *dest, const void *src, size_t n)
Not Collective, Asynchronous, Auto-dependency aware
Input Parameters#
dctx - The
PetscDeviceContext
used to copy the memorydest - The pointer to copy to
src - The pointer to copy from
n - The amount (in elements) to copy
Notes#
Both dest
and src
must have been allocated using PetscDeviceMalloc()
or
PetscDeviceCalloc()
.
This uses the sizeof()
of the src
memory type requested to determine the total memory to
be copied, therefore you should not multiply the number of elements by the sizeof()
the
type:
PetscInt *to,*from;
// correct
PetscDeviceArrayCopy(dctx,to,from,n);
// incorrect
PetscDeviceArrayCopy(dctx,to,from,n*sizeof(*from));
See PetscDeviceMemcpy()
for further discussion.
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 variablesPetscFoo->data
may not be).
See Also#
PetscDeviceMalloc()
, PetscDeviceCalloc()
, PetscDeviceFree()
,
PetscDeviceArrayZero()
, PetscDeviceMemcpy()
Level#
beginner
Location#
Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages