PetscDeviceContextForkWithStreamType#
Create a set of dependent child contexts from a parent context with a prescribed PetscStreamType
Synopsis#
#include <petscdevice.h>
PetscErrorCode PetscDeviceContextForkWithStreamType(PetscDeviceContext dctx, PetscStreamType stype, PetscInt n, PetscDeviceContext **dsub)
Not Collective, Asynchronous
Input Parameters#
dctx - The parent
PetscDeviceContext
stype - The prescribed
PetscStreamType
n - The number of children to create
Output Parameter#
dsub - The created child context(s)
Notes#
This routine creates n
edges of a DAG from a source node which are causally dependent on the
source node. This causal dependency is established as-if by calling
PetscDeviceContextWaitForContext()
on every child.
dsub
is allocated by this routine and has its lifetime bounded by dctx
. That is, dctx
expects to free dsub
(via PetscDeviceContextJoin()
) before it itself is destroyed.
This routine only accounts for work queued on dctx
up until calling this routine, any
subsequent work enqueued on dctx
has no effect on dsub
.
The PetscStreamType
of dctx
does not have to equal stype
. In fact, it is often the case
that they are different. This is useful in cases where a routine can locally exploit stream
parallelism without needing to worry about what stream type the incoming PetscDeviceContext
carries.
DAG representation#
time ->
-> dctx - |= CALL =| -\----> dctx ------>
\---> dsub[0] --->
\--> ... ------->
\-> dsub[n-1] ->
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#
PetscDeviceContextJoin()
, PetscDeviceContextSynchronize()
,
PetscDeviceContextQueryIdle()
, PetscDeviceContextWaitForContext()
Level#
intermediate
Location#
src/sys/objects/device/interface/dcontext.cxx
Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages