Reference documentation for deal.II version GIT 9fcc068bd8 2023-06-06 14:45:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Public Member Functions | Private Attributes | List of all members

#include <deal.II/base/thread_management.h>

Inheritance diagram for Threads::Thread< RT >:

Public Member Functions

 Thread (const std::function< RT()> &function)
 Thread ()=default
 Thread (const Thread< RT > &t)
void join () const
internal::return_value< RT >::reference_type return_value ()
bool valid () const
bool operator== (const Thread &t) const

Private Attributes

std::shared_ptr< internal::ThreadDescriptor< RT > > thread_descriptor

Detailed Description

template<typename RT = void>
class Threads::Thread< RT >

An object that represents a spawned thread. This object can be freely copied around in user space, and all instances will represent the same thread and can require to wait for its termination and access its return value.

Threads can be abandoned, i.e. if you just call Threads::new_thread but don't care about the returned object, or if you assign the return Threads::Thread object to an object that subsequently goes out of scope, then the thread previously created will still continue to do work. You will simply not be able to access its return value any more, and it may also happen that your program terminates before the thread has finished its work.

The default value of the template argument is void, so if the function you are calling on a new thread has no return value, you can omit the template argument.

Use std::thread or std::jthread instead.
Since this class is used in ThreadGroup, its constructors, rather than the class itself, are deprecated to allow compilation with -Werror=deprecated-declarations.

Definition at line 536 of file thread_management.h.

Constructor & Destructor Documentation

◆ Thread() [1/3]

template<typename RT = void>
Threads::Thread< RT >::Thread ( const std::function< RT()> &  function)

Construct a thread object with a function object.

Definition at line 543 of file thread_management.h.

◆ Thread() [2/3]

template<typename RT = void>
Threads::Thread< RT >::Thread ( )

Default constructor. You can't do much with a thread object constructed this way, except for assigning it a thread object that holds data created by the new_thread() functions.

◆ Thread() [3/3]

template<typename RT = void>
Threads::Thread< RT >::Thread ( const Thread< RT > &  t)

Copy constructor.

Definition at line 562 of file thread_management.h.

Member Function Documentation

◆ join()

template<typename RT = void>
void Threads::Thread< RT >::join ( ) const

Join the thread represented by this object, i.e. wait for it to finish. If you have used the default constructor of this class and have not assigned a thread object to it, then this function is a no-op.

Definition at line 572 of file thread_management.h.

◆ return_value()

template<typename RT = void>
internal::return_value<RT>::reference_type Threads::Thread< RT >::return_value ( )

Get the return value of the function of the thread. Since it is only available once the thread finishes, this function internally also calls join(). You can call this function multiple times as long as the object refers to the same task, and expect to get the same return value every time. (With the exception of the case where the returned object has been moved; see below.)

The function returns a non-const reference to the returned object, instead of the returned object. This allows writing code such as
...function returning an int...);
t.return_value() = 42; // overwrite returned value
int i = t.return_value(); // i is now 42
internal::return_value< RT >::reference_type return_value()
Thread< RT > new_thread(const std::function< RT()> &function)
You will rarely have a need to write such code. On the other hand, the function needs to return a writable (non-const) reference to support code such as this:
std::unique_ptr<int> create_int (const std::string &s)
void f()
t = Threads::new_thread (&create_int, "42");
std::unique_ptr<int> i = std::move(t.return_value());
Here, it is necessary to std::move the returned object (namely, the std::unique_ptr object) because std::unique_ptr objects can not be copied. In other words, to get the pointer out of the object returned from the thread, it needs to be moved, and in order to be moved, the current function needs to return a writable (non-const) reference.

Definition at line 622 of file thread_management.h.

◆ valid()

template<typename RT = void>
bool Threads::Thread< RT >::valid ( ) const

Return true if this object has had a thread associated with it, either by using the non-default constructor or by assignment.

Definition at line 633 of file thread_management.h.

◆ operator==()

template<typename RT = void>
bool Threads::Thread< RT >::operator== ( const Thread< RT > &  t) const

Check for equality of thread objects. Since objects of this class store an implicit pointer to an object that exists exactly once for each thread, the check is simply to compare these pointers.

Definition at line 645 of file thread_management.h.

Member Data Documentation

◆ thread_descriptor

template<typename RT = void>
std::shared_ptr<internal::ThreadDescriptor<RT> > Threads::Thread< RT >::thread_descriptor

Shared pointer to the object representing the thread, and abstracting operating system functions to work on it. This also makes sure that the object lives as long as there is at least one subscriber to it.

Definition at line 656 of file thread_management.h.

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