Merge pull request #627 from crtrott/update-parallel-semantics

Clarify parallel semantics of calling functor operator
kokkos · Feb 5, 2025 · 757c295 · 757c295
2 parents fa6ddd1 + 863fc18
commit 757c295
Show file tree

Hide file tree

Showing 3 changed files with 3 additions and 0 deletions.
diff --git a/docs/source/API/core/parallel-dispatch/parallel_for.rst b/docs/source/API/core/parallel-dispatch/parallel_for.rst
@@ -54,6 +54,7 @@ Requirements
 Semantics
 ---------
 
+* For every element of the iteration space defined in ``policy`` the functors call operator is invoked exactly once, except for ``TeamPolicy`` and ``TeamThreadRange`` where the call operator is invoked by each vector lane of the team and thread respectively.
 * Neither concurrency nor order of execution of iterations are guaranteed.
 * The call is potentially asynchronous. To guarantee a kernel has finished, a developer should call fence on the execution space on which the kernel is run.
 

diff --git a/docs/source/API/core/parallel-dispatch/parallel_reduce.rst b/docs/source/API/core/parallel-dispatch/parallel_reduce.rst
@@ -113,6 +113,7 @@ Requirements:
 Semantics
 ---------
 
+* For every element of the iteration space defined in ``policy`` the functors call operator is invoked exactly once, except for ``TeamPolicy`` and ``TeamThreadRange`` where the call operator is invoked by each vector lane of the team and thread respectively.
 * Neither concurrency nor order of execution are guaranteed.
 * The call is potentially asynchronous if the ``ReducerArgument`` is not a scalar type.
 * The ``ReducerArgument`` content will be overwritten, i.e. the value does not need to be initialized to the reduction-neutral element.

diff --git a/docs/source/API/core/parallel-dispatch/parallel_scan.rst b/docs/source/API/core/parallel-dispatch/parallel_scan.rst
@@ -58,6 +58,7 @@ Semantics
 * Neither concurrency nor order of execution are guaranteed.
 * The ``ReturnType`` content will be overwritten, i.e. the value does not need to be initialized to the reduction-neutral element.
 * The input value to the operator may contain a partial result, Kokkos may only combine the thread local contributions in the end. The operator should modify the input value according to the desired scan operation.
+* For every element of the iteration space defined in ``policy`` the functors call operator is invoked exactly once with ``final = true``.
 * It is not guaranteed that the functor will ever be called with ``final = false``.
 * The functor might be called multiple times with ``final = false`` and the user has to make sure that the behavior in this case stays the same for repeated calls.