VTK-m  1.6
Classes | Public Types | Public Member Functions | Private Member Functions | Private Attributes | List of all members
vtkm::cont::Token Class Referencefinal

A token to hold the scope of an ArrayHandle or other object. More...

#include <Token.h>

Classes

struct  ObjectReference
 
struct  ObjectReferenceImpl
 
class  Reference
 

Public Types

using ReferenceCount = vtkm::IdComponent
 Use this type to represent counts of how many tokens are holding a resource. More...
 

Public Member Functions

VTKM_CONT Token ()
 
VTKM_CONT Token (Token &&rhs)
 
VTKM_CONT ~Token ()
 
VTKM_CONT void DetachFromAll ()
 Detaches this Token from all resources to allow them to be used elsewhere or deleted. More...
 
VTKM_CONT bool IsAttached (vtkm::cont::Token::ReferenceCount *referenceCountPointer) const
 Determine if this Token is already attached to an object. More...
 
VTKM_CONT Reference GetReference () const
 Returns a reference object to this Token. More...
 
template<typename T >
VTKM_CONT void Attach (T &&object, vtkm::cont::Token::ReferenceCount *referenceCountPointer, std::unique_lock< std::mutex > &lock, std::condition_variable *conditionVariablePointer)
 Add an object to attach to the Token. More...
 
template<typename T >
VTKM_CONT void Attach (T &&object, vtkm::cont::Token::ReferenceCount *referenceCountPoiner, std::mutex *mutexPointer, std::condition_variable *conditionVariablePointer)
 Add an object to attach to the Token. More...
 

Private Member Functions

VTKM_CONT void Attach (std::unique_ptr< vtkm::cont::Token::ObjectReference > &&objectReference, vtkm::cont::Token::ReferenceCount *referenceCountPointer, std::unique_lock< std::mutex > &lock, std::condition_variable *conditionVariablePointer)
 
VTKM_CONT bool IsAttached (std::unique_lock< std::mutex > &lock, vtkm::cont::Token::ReferenceCount *referenceCountPointer) const
 

Private Attributes

std::unique_ptr< InternalStruct > Internals
 

Detailed Description

A token to hold the scope of an ArrayHandle or other object.

A Token is an object that is held in the stack or state of another object and is used when creating references to resouces that may be used by other threads. For example, when preparing an ArrayHandle or ExecutionObject for a device, a Token is given. The returned object will be valid as long as the Token remains in scope.

Member Typedef Documentation

◆ ReferenceCount

Use this type to represent counts of how many tokens are holding a resource.

Constructor & Destructor Documentation

◆ Token() [1/2]

VTKM_CONT vtkm::cont::Token::Token ( )

◆ Token() [2/2]

VTKM_CONT vtkm::cont::Token::Token ( Token &&  rhs)

◆ ~Token()

VTKM_CONT vtkm::cont::Token::~Token ( )

Member Function Documentation

◆ Attach() [1/3]

VTKM_CONT void vtkm::cont::Token::Attach ( std::unique_ptr< vtkm::cont::Token::ObjectReference > &&  objectReference,
vtkm::cont::Token::ReferenceCount referenceCountPointer,
std::unique_lock< std::mutex > &  lock,
std::condition_variable *  conditionVariablePointer 
)
private

◆ Attach() [2/3]

template<typename T >
VTKM_CONT void vtkm::cont::Token::Attach ( T &&  object,
vtkm::cont::Token::ReferenceCount referenceCountPoiner,
std::mutex *  mutexPointer,
std::condition_variable *  conditionVariablePointer 
)
inline

Add an object to attach to the Token.

To attach an object to a Token, you need the object itself, a pointer to a Token::ReferenceCount that is used to count how many Tokens hold the object, a pointer to a std::mutex used to safely use the ReferenceCount, and a pointer to a std::condition_variable that other threads will wait on if they are blocked by the Token (using the same mutex in the given unique_lock). The mutex can also be passed in as a std::unique_lock<std::mutex> to signal whether or not the mutex is already locked by the current thread.

When the Token is attached, it will increment the reference count (safely with the mutex) and store away these items. Other items will be able tell if a token is attached to the object by looking at the reference count.

When the Token is released, it will decrement the reference count (safely with the mutex) and then notify all threads waiting on the condition variable.

◆ Attach() [3/3]

template<typename T >
VTKM_CONT void vtkm::cont::Token::Attach ( T &&  object,
vtkm::cont::Token::ReferenceCount referenceCountPointer,
std::unique_lock< std::mutex > &  lock,
std::condition_variable *  conditionVariablePointer 
)
inline

Add an object to attach to the Token.

To attach an object to a Token, you need the object itself, a pointer to a Token::ReferenceCount that is used to count how many Tokens hold the object, a pointer to a std::mutex used to safely use the ReferenceCount, and a pointer to a std::condition_variable that other threads will wait on if they are blocked by the Token (using the same mutex in the given unique_lock). The mutex can also be passed in as a std::unique_lock<std::mutex> to signal whether or not the mutex is already locked by the current thread.

When the Token is attached, it will increment the reference count (safely with the mutex) and store away these items. Other items will be able tell if a token is attached to the object by looking at the reference count.

When the Token is released, it will decrement the reference count (safely with the mutex) and then notify all threads waiting on the condition variable.

◆ DetachFromAll()

VTKM_CONT void vtkm::cont::Token::DetachFromAll ( )

Detaches this Token from all resources to allow them to be used elsewhere or deleted.

◆ GetReference()

VTKM_CONT Reference vtkm::cont::Token::GetReference ( ) const

Returns a reference object to this Token.

Token objects cannot be copied and generally are not shared. However, there are cases where you need to save a reference to a Token belonging to someone else so that it can later be compared. Saving a pointer to a Token is not always safe because Tokens can be moved. To get around this problem, you can save a Reference to the Token. You cannot use the Reference to manipulate the Token in any way (because you do not own it). Rather, a Reference can just be used to compare to a Token object (or another Reference).

◆ IsAttached() [1/2]

VTKM_CONT bool vtkm::cont::Token::IsAttached ( std::unique_lock< std::mutex > &  lock,
vtkm::cont::Token::ReferenceCount referenceCountPointer 
) const
private

◆ IsAttached() [2/2]

VTKM_CONT bool vtkm::cont::Token::IsAttached ( vtkm::cont::Token::ReferenceCount referenceCountPointer) const

Determine if this Token is already attached to an object.

Given a reference counter pointer, such as would be passed to the Attach method, returns true if this Token is already attached, false otherwise.

Member Data Documentation

◆ Internals

std::unique_ptr<InternalStruct> vtkm::cont::Token::Internals
mutableprivate

The documentation for this class was generated from the following file: