Declaration of access intent for a global object. More...

#include <Tpetra_withLocalAccess.hpp>

Public Member Functions
	LocalAccess (global_object_type &G, const execution_space &execSpace, const memory_space &memSpace, const bool viewIsValid=true)
	Constructor that specifies the global object, the execution memory space instance on which to view its local data, the memory space instance on which to view its local data, and (optionally) whether the global object is valid. More...

	LocalAccess (global_object_type &G, const bool viewIsValid=true)
	Constructor that specifies the global object and (optionally) whether it is valid. More...

	LocalAccess (global_object_type &G, const execution_space &execSpace, const bool viewIsValid=true)
	Constructor that specifies the global object, the execution space instance at which to view its local data, and (optionally) whether the global object is valid. More...

	LocalAccess (global_object_type &G, const memory_space &memSpace, const bool viewIsValid=true)
	Constructor that specifies the global object, the memory space instance on which to view its local data, and (optionally) whether the global object is valid. More...

bool	isValid () const
	Is access supposed to be valid? More...

execution_space	getExecutionSpace () const
	Execution space instance, at which the user will access local data. More...

memory_space	getMemorySpace () const
	Memory space instance, on which the user will access local data. More...

this_type	valid (const bool thisIsValid) const
	Declare at run time whether you actually want to access the object. More...

template<class NewMemorySpace >
std::conditional < is_execution_space_specified, LocalAccess < global_object_type, execution_space, NewMemorySpace, access_mode > , LocalAccess < global_object_type, NewMemorySpace, access_mode > >::type	on (const NewMemorySpace &memSpace) const
	Declare intent to access this object's local data on a specific (Kokkos) memory space (instance). More...

template<class NewExecutionSpace >
std::conditional < is_memory_space_specified, LocalAccess < global_object_type, NewExecutionSpace, memory_space, access_mode > , LocalAccess < global_object_type, NewExecutionSpace, access_mode > >::type	at (const NewExecutionSpace &execSpace) const
	Declare intent to access this object's local data at a specific (Kokkos) execution space (instance). More...

Public Attributes
global_object_type &	G_
	Reference to the global object whose data the user will access. More...

execution_space	execSpace_
	Execution space instance, with which the user will access local data. More...

memory_space	memSpace_
	Memory space instance, on which the user will access local data. More...

bool	valid_
	Will I actually need to access this object? More...

Detailed Description

template<class GlobalObjectType, class... Args>
class Tpetra::Details::LocalAccess< GlobalObjectType, Args >

Declaration of access intent for a global object.

Template Parameters

GlobalObjectType	Type of the global object whose local data you want to access.
Args	Zero or more types, each of which may be a Kokkos execution space, a Kokkos memory space, or Access (see above).

Users must not make instances of this class directly. The only way they may create an instance of LocalAccess is by calling readOnly(), writeOnly(), readWrite(), or LocalAccess instance methods like at(), on(), and valid().

For X a Tpetra::MultiVector with memory_space=Kokkos::CudaUVMSpace and execution_space=Kokkos::Cuda, the following two code examples must have the same effect:

readWrite(X).on(CudaUVMSpace()).at(DefaultHostExecutionSpace());

and

readWrite(X).at(DefaultHostExecutionSpace()).on(CudaUVMSpace());

That effect should be: "I intend to view X's local data in read-and-write fashion at host execution, on a UVM allocation." Given Tpetra's current design (as of 26 Jan 2020), if X needs sync to host, then that implies a fence, to ensure that any device writes to X's local data are done.

This means that LocalAccess needs to be able to know whether the user has explicitly specified an execution space in which to access local data. Here is how on behaves:

If the input LocalAccess has no execution space explicitly specified, then do not constrain it. withLocalAccess will assign a default execution space. (This makes the "at after on" example above work correctly.)
Else, use the input LocalAccess' execution_space. The caller is responsible for knowing whether NewMemorySpace is accessible from execution_space.

Here is how at behaves:

If the input LocalAccess has no memory space explicitly specified, then do not constrain it. withLocalAccess will assign a default memory space. (This makes the "on after at" example above work correctly.)
Else, use the input LocalAccess' memory_space. The caller is responsible for knowing whether NewExecutionSpace can access memory_space.

The general behavior is that at() and on() both only constrain the one thing that the user specified. Only the "final" LocalAccess object determines the behavior of withLocalAccess.

For these reasons, LocalAccess needs to be able to distinguish between "the user explicitly assigned an {execution, memory} space," and "use the default {execution, memory} space." This is why LocalAccess has a template parameter pack.

Definition at line 460 of file Tpetra_withLocalAccess.hpp.

Constructor & Destructor Documentation

template<class GlobalObjectType , class... Args>

Tpetra::Details::LocalAccess< GlobalObjectType, Args >::LocalAccess	(	global_object_type &	G,
		const execution_space &	execSpace,
		const memory_space &	memSpace,
		const bool	viewIsValid = `true`
	)

inline

Constructor that specifies the global object, the execution memory space instance on which to view its local data, the memory space instance on which to view its local data, and (optionally) whether the global object is valid.

Users must NOT call the LocalAccess constructor directly. They should instead start by calling readOnly, writeOnly, or readWrite above. They may then use instance methods like at(), on(), or valid() (see below).

G is a reference, because we only access it in a delimited scope. G is nonconst, because even read-only local access may modify G. For example, G may give access to its local data via lazy allocation of a data structure that differs from its normal internal storage format.

Definition at line 516 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

Tpetra::Details::LocalAccess< GlobalObjectType, Args >::LocalAccess	(	global_object_type &	G,
		const bool	viewIsValid = `true`
	)

inline

Constructor that specifies the global object and (optionally) whether it is valid.

Definition at line 528 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

Tpetra::Details::LocalAccess< GlobalObjectType, Args >::LocalAccess	(	global_object_type &	G,
		const execution_space &	execSpace,
		const bool	viewIsValid = `true`
	)

inline

Constructor that specifies the global object, the execution space instance at which to view its local data, and (optionally) whether the global object is valid.

Definition at line 539 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

Tpetra::Details::LocalAccess< GlobalObjectType, Args >::LocalAccess	(	global_object_type &	G,
		const memory_space &	memSpace,
		const bool	viewIsValid = `true`
	)

inline

Constructor that specifies the global object, the memory space instance on which to view its local data, and (optionally) whether the global object is valid.

Definition at line 551 of file Tpetra_withLocalAccess.hpp.

Member Function Documentation

template<class GlobalObjectType , class... Args>

bool Tpetra::Details::LocalAccess< GlobalObjectType, Args >::isValid ( ) const

inline

Is access supposed to be valid?

If not, then you may not access the global object's local data inside a withLocalAccess scope governed by this LocalAccess instance.

See valid(const bool) below.

Definition at line 567 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

execution_space Tpetra::Details::LocalAccess< GlobalObjectType, Args >::getExecutionSpace ( ) const

inline

Execution space instance, at which the user will access local data.

Definition at line 571 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

memory_space Tpetra::Details::LocalAccess< GlobalObjectType, Args >::getMemorySpace ( ) const

inline

Memory space instance, on which the user will access local data.

Definition at line 575 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

this_type Tpetra::Details::LocalAccess< GlobalObjectType, Args >::valid ( const bool thisIsValid ) const

inline

Declare at run time whether you actually want to access the object.

Parameters

thisIsValid [in] If false, then the caller promises that they won't actually access the object.

If thisIsValid is false, implementations should not spend any effort getting the master local object. This may save time on allocating temporary space, copying from device to host, etc. This implies that implementations must be able to construct "null" / empty master local objects.

Definition at line 589 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

template<class NewMemorySpace >

std::conditional< is_execution_space_specified, LocalAccess<global_object_type, execution_space, NewMemorySpace, access_mode>, LocalAccess<global_object_type, NewMemorySpace, access_mode> >::type Tpetra::Details::LocalAccess< GlobalObjectType, Args >::on ( const NewMemorySpace & memSpace ) const

inline

Declare intent to access this object's local data on a specific (Kokkos) memory space (instance).

Definition at line 603 of file Tpetra_withLocalAccess.hpp.

template<class GlobalObjectType , class... Args>

template<class NewExecutionSpace >

std::conditional< is_memory_space_specified, LocalAccess<global_object_type, NewExecutionSpace, memory_space, access_mode>, LocalAccess<global_object_type, NewExecutionSpace, access_mode> >::type Tpetra::Details::LocalAccess< GlobalObjectType, Args >::at ( const NewExecutionSpace & execSpace ) const