1/*N ASYNC_API 2 Asynchronous API Notes: 3 This routine is explicitly marked as exhibiting asynchronous behavior. Asynchronous 4 behavior implies that routines launching operations on (or associated with) a 5 `PetscDeviceContext` may return to the caller before the operation has completed. 6 7 Sequential Consistency\: 8 9 Operations using the _same_ `PetscDeviceContext` which access objects or memory regions 10 are ordered per the language specification. 11 12 Operations using _separate_ `PetscDeviceContext`s which access the _same_ object or 13 memory region are strongly write-ordered. That is, the following operations\: 14 15 - `write-write` 16 - `write-read` 17 - `read-write` 18 19 are strongly ordered. Formally\: 20 21 _Given an operation `A-B` (e.g. `A` = `write`, `B` = `read`) on an object or memory 22 region `M` such that `A` "happens-before" `B`, where `A` uses `PetscDeviceContext` `X` 23 and `B` uses `PetscDeviceContext` `Y`, then `B` shall not begin before `A` 24 completes. This implies that any side-effects resulting from `A` are also observed by 25 `B`._ 26 27 Note the omission of `read-read`; there is no implied ordering between separate 28 `PetscDeviceContext`s for consecutive reads. 29 30 Operations using _separate_ `PetscDeviceContext`s which access _separate_ objects or 31 memory regions may execute in an arbitrary order and offer no guarantee of sequential 32 consistency. 33 34 Memory Consistency\: 35 36 If this routine modifies the participating object(s) then -- unless otherwise stated -- 37 the contents of any externally held references to internal data structures should be 38 considered to be in an undefined state. A well-defined state can only be restored by 39 re-acquiring these references through the appropriate API or by calling 40 `PetscDeviceContextSynchronize()`. 41 42 Unless otherwise stated, exceptions to this rule are\: 43 44 - References returned by the routine itself. If a routine returns a pointer, the value 45 of the top-most pointer is guaranteed to always be valid. For example, given a routine 46 which asynchronously allocates memory and returns a pointer to the memory, the value 47 of said pointer is immediately valid but dereferencing the pointer may not be. 48 - References to structures. If a routine returns a `PetscFoo`, or array thereof then the 49 objects themselves are always valid (though their member variables `PetscFoo->data` 50 may not be). 51N*/ 52