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

using vtkm::cont::Token::ReferenceCount = vtkm::IdComponent

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:

Token.h

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes