vtkSMPThreadLocal< T > Class Template Reference

Thread local storage for VTK objects. More...

#include <vtkSMPThreadLocal.h>

Inheritance diagram for vtkSMPThreadLocal< T >:

Public Types
typedef vtk::detail::smp::vtkSMPThreadLocalAPI< T >::iterator	iterator
	Subset of the standard iterator API.

Public Member Functions
	vtkSMPThreadLocal ()
	Default constructor.
	vtkSMPThreadLocal (const T &exemplar)
	Constructor that allows the specification of an exemplar object which is used when constructing objects when Local() is first called.
T &	Local ()
	This needs to be called mainly within a threaded execution path.
size_t	size ()
	Return the number of thread local objects that have been initialized.
iterator	begin ()
	Returns a new iterator pointing to the beginning of the local storage container.
iterator	end ()
	Returns a new iterator pointing to past the end of the local storage container.

Detailed Description

template<typename T>
class vtkSMPThreadLocal< T >

Thread local storage for VTK objects.

A thread local object is one that maintains a copy of an object of the template type for each thread that processes data. vtkSMPThreadLocal creates storage for all threads but the actual objects are created the first time Local() is called. Note that some of the vtkSMPThreadLocal API is not thread safe. It can be safely used in a multi-threaded environment because Local() returns storage specific to a particular thread, which by default will be accessed sequentially. It is also thread-safe to iterate over vtkSMPThreadLocal as long as each thread creates its own iterator and does not change any of the thread local objects.

A common design pattern in using a thread local storage object is to write/accumulate data to local object when executing in parallel and then having a sequential code block that iterates over the whole storage using the iterators to do the final accumulation.

Warning

There is absolutely no guarantee to the order in which the local objects will be stored and hence the order in which they will be traversed when using iterators. You should not even assume that two vtkSMPThreadLocal populated in the same parallel section will be populated in the same order. For example, consider the following

vtkSMPThreadLocal<int> Foo;
vtkSMPThreadLocal<int> Bar;
class AFunctor
{
   void Initialize() const
   {
       int& foo = Foo.Local();
       int& bar = Bar.Local();
       foo = random();
       bar = foo;
   }
 
   void operator()(vtkIdType, vtkIdType) const
   {}
};
 
AFunctor functor;
vtkParalllelUtilities::For(0, 100000, functor);
 
vtkSMPThreadLocal<int>::iterator itr1 = Foo.begin();
vtkSMPThreadLocal<int>::iterator itr2 = Bar.begin();
while (itr1 != Foo.end())
{
  assert(*itr1 == *itr2);
  ++itr1; ++itr2;
}

Warning

It is possible and likely that the assert() will fail using the TBB backend. So if you need to store values related to each other and iterate over them together, use a struct or class to group them together and use a thread local of that class.

See also

vtkSMPThreadLocalObject

Definition at line 87 of file vtkSMPThreadLocal.h.

Member Typedef Documentation

iterator

template<typename T >

typedef vtk::detail::smp::vtkSMPThreadLocalAPI<T>::iterator vtkSMPThreadLocal< T >::iterator

Subset of the standard iterator API.

The most common design pattern is to use iterators in a sequential code block and to use only the thread local objects in parallel code blocks. It is thread safe to iterate over the thread local containers as long as each thread uses its own iterator and does not modify objects in the container.

Definition at line 132 of file vtkSMPThreadLocal.h.

Constructor & Destructor Documentation

vtkSMPThreadLocal() [1/2]

template<typename T >

vtkSMPThreadLocal< T >::vtkSMPThreadLocal ( )

inline

Default constructor.

Creates a default exemplar.

Definition at line 93 of file vtkSMPThreadLocal.h.

vtkSMPThreadLocal() [2/2]

template<typename T >

vtkSMPThreadLocal< T >::vtkSMPThreadLocal ( const T &  exemplar )

inlineexplicit

Constructor that allows the specification of an exemplar object which is used when constructing objects when Local() is first called.

Note that a copy of the exemplar is created using its copy constructor.

Definition at line 103 of file vtkSMPThreadLocal.h.

Member Function Documentation

Local()

template<typename T >

T & vtkSMPThreadLocal< T >::Local ( )

inline

This needs to be called mainly within a threaded execution path.

It will create a new object (local to the thread so each thread get their own when calling Local) which is a copy of exemplar as passed to the constructor (or a default object if no exemplar was provided) the first time it is called. After the first time, it will return the same object.

Definition at line 116 of file vtkSMPThreadLocal.h.

size()

template<typename T >

size_t vtkSMPThreadLocal< T >::size ( )

inline

Return the number of thread local objects that have been initialized.

Definition at line 121 of file vtkSMPThreadLocal.h.

begin()

template<typename T >

iterator vtkSMPThreadLocal< T >::begin ( )

inline

Returns a new iterator pointing to the beginning of the local storage container.

Thread safe.

Definition at line 138 of file vtkSMPThreadLocal.h.

end()

template<typename T >

iterator vtkSMPThreadLocal< T >::end ( )

inline

Returns a new iterator pointing to past the end of the local storage container.

Thread safe.

Definition at line 144 of file vtkSMPThreadLocal.h.

---

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

• Common/Core/vtkSMPThreadLocal.h