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