Merge pull request #242 from antoinemeyer5/120-API-core-policies-Nest…

…edPolicies #120: API-core-policies-NestedPolicies from md to rst
kokkos · Feb 1, 2023 · 1ca692f · 1ca692f
2 parents a682f8a + 3552e76
commit 1ca692f
Show file tree

Hide file tree

Showing 2 changed files with 126 additions and 122 deletions.
diff --git a/docs/source/API/core/policies/NestedPolicies.md b/docs/source/API/core/policies/NestedPolicies.md
diff --git a/docs/source/API/core/policies/NestedPolicies.rst b/docs/source/API/core/policies/NestedPolicies.rst
@@ -0,0 +1,126 @@
+``NestedPolicies``
+==================
+
+.. role:: cppkokkos(code)
+    :language: cppkokkos
+
+Header File: ``<Kokkos_Core.hpp>``
+
+List
+----
+
+``Kokkos::PerTeam``
+~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::PerThread``
+~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::TeamThreadRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::TeamThreadMDRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::TeamVectorRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::TeamVectorMDRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::ThreadVectorRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Kokkos::ThreadVectorMDRange``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|
+
+Usage
+~~~~~
+
+.. code-block:: cpp
+
+    parallel_for(TeamThreadRange(team,begin,end), [=] (int i) {});
+    parallel_for(ThreadVectorRange(team,begin,end), [=] (int i) {});
+    single(PerTeam(team), [=] () {});
+    single(PerThread(team), [=] () {});
+
+Nested policies can be used for nested parallel patterns. In contrast to global policies, the public interface for nested policies is implemented as functions, in order to enable implicit templating on the execution space type via the team handle.
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: cpp
+
+    Impl::TeamThreadRangeBoundariesStruct TeamThreadRange(TeamMemberType team, IndexType count);
+    Impl::TeamThreadRangeBoundariesStruct TeamThreadRange(TeamMemberType team, IndexType begin, IndexType end);
+    Impl::ThreadVectorRangeBoundariesStruct ThreadVectorRange(TeamMemberType team, IndexType count);
+    Impl::ThreadVectorRangeBoundariesStruct ThreadVectorRange(TeamMemberType team, IndexType begin, IndexType end);
+    Impl::ThreadSingleStruct PerTeam(TeamMemberType team);
+    Impl::VectorSingleStruct PerThread(TeamMemberType team);
+
+Description
+~~~~~~~~~~~
+
+.. cppkokkos:function:: Impl::TeamThreadRangeBoundariesStruct TeamThreadRange(TeamMemberType team, IndexType count);
+
+    Splits the index range ``0`` to ``count-1`` over the threads of the team. This call is potentially a synchronization point for the team, and thus must meet the requirements of ``team_barrier``.
+        - ``team``: object meeting the requirements of TeamHandle
+        - ``count``: index range length.
+
+.. cppkokkos:function:: Impl::TeamThreadRangeBoundariesStruct TeamThreadRange(TeamMemberType team, IndexType begin, IndexType end);
+
+    Splits the index range ``begin`` to ``end-1`` over the threads of the team. This call is potentially a synchronization point for the team, and thus must meet the requirements of ``team_barrier``.
+        - ``team``: object meeting the requirements of TeamHandle
+        - ``begin``: start index.
+        - ``end``: end index.
+
+.. cppkokkos:function:: Impl::ThreadVectorRangeBoundariesStruct ThreadVectorRange(TeamMemberType team, IndexType count);
+
+    Splits the index range ``0`` to ``count-1`` over the vector lanes of the calling thread. It is not legal to call this function inside of a vector level loop.
+        - ``team``: object meeting the requirements of TeamHandle
+        - ``count``: index range length.
+
+.. cppkokkos:function:: Impl::ThreadVectorRangeBoundariesStruct ThreadVectorRange(TeamMemberType team, IndexType begin, IndexType end);
+
+    Splits the index range ``begin`` to ``end-1`` over the vector lanes of the calling thread. It is not legal to call this function inside of a vector level loop.
+        - ``team``: object meeting the requirements of TeamHandle
+        - ``begin``: start index.
+        - ``end``: end index.
+
+.. cppkokkos:function:: Impl::ThreadSingleStruct PerTeam(TeamMemberType team);
+
+    When used in conjunction with the ``single`` pattern restricts execution to a single vector lane in the calling team. While not a synchronization event, this call must be encountered by the entire team, and thus meet the calling requirements of ``team_barrier``.
+        - ``team``: object meeting the requirements of TeamHandle
+
+.. cppkokkos:function:: Impl::VectorSingleStruct PerThread(TeamMemberType team);
+
+    When used in conjunction with the ``single`` pattern restricts execution to a single vector lane in the calling thread. It is not legal to call this function inside of a vector level loop.
+        - ``team``: object meeting the requirements of TeamHandle
+
+Examples
+~~~~~~~~
+
+.. code-block:: cpp
+
+    typedef TeamPolicy<>::member_type team_handle;
+    parallel_for(TeamPolicy<>(N,AUTO,4), KOKKOS_LAMBDA (const team_handle& team) {
+        int n = team.league_rank();
+        parallel_for(TeamThreadRange(team,M), [&] (const int& i) {
+            int thread_sum;
+            parallel_reduce(ThreadVectorRange(team,K), [&] (const int& j, int& lsum) {
+                //...
+            },thread_sum);
+            single(PerThread(team), [&] () {
+                A(n,i) += thread_sum;
+            });
+        });
+        team.team_barrier();
+        int team_sum;
+        parallel_reduce(TeamThreadRange(team,M), [&] (const int& i, int& lsum) {
+            lsum += A(n,i);
+        },team_sum);
+        single(PerTeam(team),[&] () {
+            A_rowsum(n) += team_sum;
+        });
+    });