Skip to content
This repository was archived by the owner on Apr 15, 2024. It is now read-only.

Kokkos::TeamHandleConcept

Jump to bottom
Christian Trott (crtrott) edited this page Aug 17, 2018 · 6 revisions

Kokkos::TeamHandleConcept

Header File: Kokkos_Core.hpp

TeamHandleConcept defines the concept for the member_type of TeamPolicy and TeamTask. The actual type is defined through the policies, but meets the following API requirements. Note that the specific classes are only part of the public API as provided by TeamPolicy and TeamTask and only their parts as defined by the TeamHandleConcept. The actual name of the class, as well as potential template parameters, existing constructors, member functions going beyond the concept, etc., are NOT part of the public Kokkos API and are thus subject to change.

Synopsis

class TeamHandleConcept {
  public:
  // Constructor, Destructor, Assignment
  TeamHandleConcept( TeamHandleConcept && ) = default ;
  TeamHandleConcept( TeamHandleConcept const & ) = default ;
  ~TeamHandleConcept() = default ;
  TeamHandleConcept & operator = ( TeamHandleConcept && ) = default ;
  TeamHandleConcept & operator = ( TeamHandleConcept const & ) = default ;

  // Indices
  KOKKOS_INLINE_FUNCTION
  int team_rank() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int team_size() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int league_rank() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int league_size() const noexcept;

  // Scratch Space
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & team_shmem() const;
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & team_scratch(int level) const;
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & thread_scratch(int level) const;

  // Team collectives
  KOKKOS_INLINE_FUNCTION 
  void team_barrier() const noexcept;
  template<typename T>
  KOKKOS_INLINE_FUNCTION
  void team_broadcast( T & value , const int source_team_rank ) const noexcept;
  template<class Closure, typename T>
  KOKKOS_INLINE_FUNCTION
  void team_broadcast( Closure const & f , T & value , const int source_team_rank) const noexcept;
  template< typename ReducerType >
  KOKKOS_INLINE_FUNCTION
  void team_reduce( ReducerType const & reducer ) const noexcept;
  template< typename T >
  KOKKOS_INLINE_FUNCTION
  T team_scan( T const & value , T * const global = 0 ) const noexcept;
};

Public Class Members

Constructors

  • TeamHandleConcept()
TeamHandleConcept(TeamHandleConcept && )
TeamHandleConcept(const TeamHandleConcept &)
~TeamHandleConcept()
    Default, move and copy constructors as well as destructor.

Assignment

  • TeamHandleConcept & operator = ( TeamHandleConcept && )
    Move assignment.
  • TeamHandleConcept & operator = ( const TeamHandleConcept & )
    Assignment operators. Returns: *this.

Index Queries

  • inline int team_size() const noexcept;
    Returns: the number of threads associated with the team.
  • inline int team_rank() const noexcept;
    Returns: the index i of the calling thread within the team with 0 <= i < team_size() 
  • inline int league_size() const noexcept;
    Returns: the number of teams/workitems launched in the kernel.
  • inline int league_rank() const noexcept;
    Returns: the index i of the calling team within the league with 0 <= i < league_size()

Scratch Space Control

  • inline const scratch_memory_space & team_scratch(int level) const;
    This function returns a scratch memory handle shared by all threads in a team, which allows access to scratch memory. This handle can be given as the first argument to a Kokkos::View to make it use scratch memory.
    • level: The level of requested scratch memory is either 0 or 1. Returns: a scratch memory handle to the team shared scratch memory specified by level.
  • inline const scratch_memory_space & thread_scratch(int level) const;
    This function returns a scratch memory handle specific to the calling thread, which allows access to its private scratch memory. This handle can be given as the first argument to a Kokkos::View to make it use scratch memory.
    • level: The level of requested scratch memory is either 0 or 1. Returns: a scratch memory handle to the thread scratch memory specified by level.
  • inline const scratch_memory_space & team_shmem() const;
    Equivalent to calling team_scratch(0).

Team Collective Operations

The following functions must be called collectively by all members of a team. These calls must be lexically the same call, i.e. it is not legal to have some members of a team call a collective in one branch and the others in another branch of the code (see example).

  • inline void team_barrier() const noexcept;
    All members of the team wait at the barrier, until the whole team arrived. This also issues a memory fence.
  • template<class T>
inline void team_broadcast( T & var , const int source_team_rank ) const noexcept;
    After this call var contains for every member of the team the value of var from the thread for which team_rank() == source_team_rank.
    • var: a variable of type T which gets overwritten by the value of var from the source rank.
    • source_team_rank: identifies the broadcasting member of the team.
  • template<class Closure, class T>
inline void team_broadcast( Closure const & f, T & var , const int source_team_rank ) const noexcept;
    After this call var contains for every member of the team the value of var from the thread for which team_rank() == source_team_rank after applying f.
    • f: a function object with an void operator() ( T & ) which is applied to var before broadcasting it.
    • var: a variable of type T which gets overwritten by the value of f(var) from the source rank.
    • source_team_rank: identifies the broadcasting member of the team.
  • template< class ReducerType > 
inline void team_reduce( ReducerType const & reducer ) const noexcept;
    Performs a reduction accross all members of the team as specified by reducer. ReducerType must meet the concept of Kokkos::Reducer.
  • template< class T >
inline T team_scan( const T & var , T * const global = NULL ) cosnt noexcept;
    Performs an exclusive scan over the var provided by the team members. Let t = team_rank() and VALUES[t] the value of var from thread t. Returns: VALUES[0] + VALUES[1] + ...+ VALUES[t-1] or zero for t==0.
    • global if provided will be set to VALUES[0] + VALUES[1] + ...+ VALUES[team_size()-1], must be the same pointer for every team member.

Examples

typedef TeamPolciy<...> policy_type;
parallel_for(policy_type(N,TEAM_SIZE).set_scratch_size(PerTeam(0,4096)), 
             KOKKOS_LAMBDA (const typename policy_type::member_type& team_handle) {
  int ts = team_handle.team_size(); // returns TEAM_SIZE
  int tid = team_handle.team_rank(); // returns a number between 0 and TEAM_SIZE
  int ls = team_handle.league_size(); // returns N
  int lid = team_handle.league_rank(); // returns a number between 0 and N

  int value = tid * 5;
  team_handle.team_broadcast(value, 3); 
  // value==15 on every thread
  value += tid;
  team_handle.team_broadcast([&] (int & var) { var*=2 }, value, 2); 
  // value==34 on every thread
  int global; 
  int scan = team_handle.team_scan(tid+1, &global);
  // scan == tid*(tid+1)/2 on every thread
  // global == ts*(ts-1)/2 on every thread
  Kokkos::View<int*, policy_type::execution_space::scratch_memory_type> 
    a(team_handle.team_scratch(0), 1024); 
  
});

new here from public (looks like a reorg)

Kokkos::TeamHandleConcept

Header File: Kokkos_Core.hpp

TeamHandleConcept defines the concept for the member_type of TeamPolicy and TeamTask. The actual type is defined through the policies, but meets the following API requirements. Note that the specific classes are only part of the public API as provided by TeamPolicy and TeamTask and only their parts as defined by the TeamHandleConcept. The actual name of the class, as well as potential template parameters, existing constructors, member functions going beyond the concept, etc., are NOT part of the public Kokkos API and are thus subject to change.

Synopsis

class TeamHandleConcept {
  public:
  // Constructor, Destructor, Assignment
  TeamHandleConcept( TeamHandleConcept && ) = default ;
  TeamHandleConcept( TeamHandleConcept const & ) = default ;
  ~TeamHandleConcept() = default ;
  TeamHandleConcept & operator = ( TeamHandleConcept && ) = default ;
  TeamHandleConcept & operator = ( TeamHandleConcept const & ) = default ;

  // Indices
  KOKKOS_INLINE_FUNCTION
  int team_rank() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int team_size() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int league_rank() const noexcept;
  KOKKOS_INLINE_FUNCTION
  int league_size() const noexcept;

  // Scratch Space
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & team_shmem() const;
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & team_scratch(int level) const;
  KOKKOS_INLINE_FUNCTION
  const scratch_memory_space & thread_scratch(int level) const;

  // Team collectives
  KOKKOS_INLINE_FUNCTION 
  void team_barrier() const noexcept;
  template<typename T>
  KOKKOS_INLINE_FUNCTION
  void team_broadcast( T & value , const int source_team_rank ) const noexcept;
  template<class Closure, typename T>
  KOKKOS_INLINE_FUNCTION
  void team_broadcast( Closure const & f , T & value , const int source_team_rank) const noexcept;
  template< typename ReducerType >
  KOKKOS_INLINE_FUNCTION
  void team_reduce( ReducerType const & reducer ) const noexcept;
  template< typename T >
  KOKKOS_INLINE_FUNCTION
  T team_scan( T const & value , T * const global = 0 ) const noexcept;
};

Public Class Members

Constructors

  • TeamHandleConcept()
TeamHandleConcept(TeamHandleConcept && )
TeamHandleConcept(const TeamHandleConcept &)
~TeamHandleConcept()
    Default, move and copy constructors as well as destructor.

Assignment

  • TeamHandleConcept & operator = ( TeamHandleConcept && )
    Move assignment.
  • TeamHandleConcept & operator = ( const TeamHandleConcept & )
    Assignment operators. Returns: *this.

Index Queries

  • inline int team_size() const noexcept;
    Returns: the number of threads associated with the team.
  • inline int team_rank() const noexcept;
    Returns: the index i of the calling thread within the team with 0 <= i < team_size() 
  • inline int league_size() const noexcept;
    Returns: the number of teams/workitems launched in the kernel.
  • inline int league_rank() const noexcept;
    Returns: the index i of the calling team within the league with 0 <= i < league_size()

Scratch Space Control

  • inline const scratch_memory_space & team_scratch(int level) const;
    This function returns a scratch memory handle shared by all threads in a team, which allows access to scratch memory. This handle can be given as the first argument to a Kokkos::View to make it use scratch memory.
    • level: The level of requested scratch memory is either 0 or 1. Returns: a scratch memory handle to the team shared scratch memory specified by level.
  • inline const scratch_memory_space & thread_scratch(int level) const;
    This function returns a scratch memory handle specific to the calling thread, which allows access to its private scratch memory. This handle can be given as the first argument to a Kokkos::View to make it use scratch memory.
    • level: The level of requested scratch memory is either 0 or 1. Returns: a scratch memory handle to the thread scratch memory specified by level.
  • inline const scratch_memory_space & team_shmem() const;
    Equivalent to calling team_scratch(0).

Team Collective Operations

The following functions must be called collectively by all members of a team. These calls must be lexically the same call, i.e. it is not legal to have some members of a team call a collective in one branch and the others in another branch of the code (see example).

  • inline void team_barrier() const noexcept;
    All members of the team wait at the barrier, until the whole team arrived. This also issues a memory fence.
  • template<class T>
inline void team_broadcast( T & var , const int source_team_rank ) const noexcept;
    After this call var contains for every member of the team the value of var from the thread for which team_rank() == source_team_rank.
    • var: a variable of type T which gets overwritten by the value of var from the source rank.
    • source_team_rank: identifies the broadcasting member of the team.
  • template<class Closure, class T>
inline void team_broadcast( Closure const & f, T & var , const int source_team_rank ) const noexcept;
    After this call var contains for every member of the team the value of var from the thread for which team_rank() == source_team_rank after applying f.
    • f: a function object with an void operator() ( T & ) which is applied to var before broadcasting it.
    • var: a variable of type T which gets overwritten by the value of f(var) from the source rank.
    • source_team_rank: identifies the broadcasting member of the team.
  • template< class ReducerType > 
inline void team_reduce( ReducerType const & reducer ) const noexcept;
    Performs a reduction accross all members of the team as specified by reducer. ReducerType must meet the concept of Kokkos::Reducer.
  • template< class T >
inline T team_scan( const T & var , T * const global = NULL ) cosnt noexcept;
    Performs an exclusive scan over the var provided by the team members. Let t = team_rank() and VALUES[t] the value of var from thread t. Returns: VALUES[0] + VALUES[1] + ...+ VALUES[t-1] or zero for t==0.
    • global if provided will be set to VALUES[0] + VALUES[1] + ...+ VALUES[team_size()-1], must be the same pointer for every team member.

Examples

typedef TeamPolciy<...> policy_type;
parallel_for(policy_type(N,TEAM_SIZE).set_scratch_size(PerTeam(0,4096)), 
             KOKKOS_LAMBDA (const typename policy_type::member_type& team_handle) {
  int ts = team_handle.team_size(); // returns TEAM_SIZE
  int tid = team_handle.team_rank(); // returns a number between 0 and TEAM_SIZE
  int ls = team_handle.league_size(); // returns N
  int lid = team_handle.league_rank(); // returns a number between 0 and N

  int value = tid * 5;
  team_handle.team_broadcast(value, 3); 
  // value==15 on every thread
  value += tid;
  team_handle.team_broadcast([&] (int & var) { var*=2 }, value, 2); 
  // value==34 on every thread
  int global; 
  int scan = team_handle.team_scan(tid+1, &global);
  // scan == tid*(tid+1)/2 on every thread
  // global == ts*(ts-1)/2 on every thread
  Kokkos::View<int*, policy_type::execution_space::scratch_memory_type> 
    a(team_handle.team_scratch(0), 1024); 
  
});

Home:

Programming Guide

Content: Core

  1. Introduction
  2. Machine Model
  3. Programming Model
  4. Compiling
  5. Initialization
  6. View
  7. Parallel Dispatch
  8. Hierarchical Parallelism
  9. Custom Reductions
  10. Atomic Operations
  11. Subviews
  12. Interoperability
  13. Kokkos and Virtual Functions

Content: Containers

  1. Dual View
  2. Dynamic Rank View
  3. Dynamic Length View
  4. Offset View
  5. Unordered Map

Content: Algorithms

  1. Sorting
  2. Random Numbers
  3. Iterators
  4. Std Algorithms
    1. NonModSequenceOps
    2. ModSeqOps
    3. PartioningOps

API Reference

Content: Alphabetical

Content: Core

  1. Initialization and Finalization
  2. View
  3. Data Parallelism
  4. Execution Policies
  5. Spaces
  6. Task Parallelism
  7. Utilities
  8. STL Compatibility
  9. Numerics
  10. Detection Idiom

Content: Containers

Content: Algorithms

  1. Sort
  2. Random Number

Use Cases

  1. MPI Halo Exchange
  2. ScatterView Average To Nodes
  3. Tightly nested loops
  4. Using Virtual Functions
  5. Classes and Functors
  6. Overlapping Host and Device work
  7. Tasking
  8. Fortran Interop
  9. SoA and AoSoA with Cabana

A Guide to Kokkos Testing and Issue Tracking

  1. Requirement Tracking
  2. Testing Processes
  3. Testing Workflow Components
  4. Kokkos Testing
  5. Testing Process Details
Clone this wiki locally