...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
#include <boost/thread/thread.hpp> namespace boost { class thread; void swap(thread& lhs,thread& rhs) noexcept; namespace this_thread { thread::id get_id() noexcept; template<typename TimeDuration> void yield() noexcept; // DEPRECATED template <class Clock, class Duration> void sleep_until(const chrono::time_point<Clock, Duration>& abs_time); template <class Rep, class Period> void sleep_for(const chrono::duration<Rep, Period>& rel_time); template<typename Callable> void at_thread_exit(Callable func); // EXTENSION void interruption_point(); // EXTENSION bool interruption_requested() noexcept; // EXTENSION bool interruption_enabled() noexcept; // EXTENSION class disable_interruption; // EXTENSION class restore_interruption; // EXTENSION #if defined BOOST_THREAD_USES_DATETIME template <TimeDuration> void sleep(TimeDuration const& rel_time); // DEPRECATED void sleep(system_time const& abs_time); // DEPRECATED #endif } class thread_group; // EXTENSION }
The boost::thread
class is responsible for launching and managing threads. Each boost::thread
object represents a single
thread of execution, or Not-a-Thread, and at most one
boost::thread
object represents a given thread of execution: objects of type boost::thread
are not copyable.
Objects of type boost::thread
are movable, however, so
they can be stored in move-aware containers, and returned from functions.
This allows the details of thread creation to be wrapped in a function.
boost::thread make_thread(); void f() { boost::thread some_thread=make_thread(); some_thread.join(); }
Note | |
---|---|
On compilers that support rvalue references, For other compilers, move support is provided with a move emulation layer, so containers must explicitly detect that move emulation layer. See <boost/thread/detail/move.hpp> for details. |
A new thread is launched by passing an object of a callable type that can
be invoked with no parameters to the constructor. The object is then copied
into internal storage, and invoked on the newly-created thread of execution.
If the object must not (or cannot) be copied, then boost::ref
can be used to pass in a reference to the function object. In this case,
the user of Boost.Thread must ensure that
the referred-to object outlives the newly-created thread of execution.
struct callable { void operator()(); }; boost::thread copies_are_safe() { callable x; return boost::thread(x); } // x is destroyed, but the newly-created thread has a copy, so this is OK boost::thread oops() { callable x; return boost::thread(boost::ref(x)); } // x is destroyed, but the newly-created thread still has a reference // this leads to undefined behaviour
If you wish to construct an instance of boost::thread
with a function or callable
object that requires arguments to be supplied, this can be done by passing
additional arguments to the boost::thread
constructor:
void find_the_question(int the_answer); boost::thread deep_thought_2(find_the_question,42);
The arguments are copied into the internal thread
structure: if a reference is required, use boost::ref
,
just as for references to callable functions.
There is an unspecified limit on the number of additional arguments that can be passed.
Thread launched in this way are created with implementation defined thread attributes as stack size, scheduling, priority, ... or any platform specific attributes. It is not evident how to provide a portable interface that allows the user to set the platform specific attributes. Boost.Thread stay in the middle road through the class thread::attributes which allows to set at least in a portable way the stack size as follows:
boost::thread::attributes attrs; attrs.set_size(4096*10); boost::thread deep_thought_2(attrs, find_the_question, 42);
Even for this simple attribute there could be portable issues as some platforms could require that the stack size should have a minimal size and/or be a multiple of a given page size. The library adapts the requested size to the platform constraints so that the user doesn't need to take care of it.
This is the single attribute that is provided in a portable way. In order to set any other thread attribute at construction time the user needs to use non portable code.
On PThread platforms the user will need to get the thread attributes handle and use it for whatever attribute.
Next follows how the user could set the stack size and the scheduling policy on PThread platforms.
boost::thread::attributes attrs; // set portable attributes // ... attr.set_stack_size(4096*10); #if defined(BOOST_THREAD_PLATFORM_WIN32) // ... window version #elif defined(BOOST_THREAD_PLATFORM_PTHREAD) // ... pthread version pthread_attr_setschedpolicy(attr.get_native_handle(), SCHED_RR); #else #error "Boost threads unavailable on this platform" #endif boost::thread th(attrs, find_the_question, 42);
On Windows platforms it is not so simple as there is no type that compiles the thread attributes. There is a linked to the creation of a thread on Windows that is emulated via the thread::attributes class. This is the LPSECURITY_ATTRIBUTES lpThreadAttributes. Boost.Thread provides a non portable set_security function so that the user can provide it before the thread creation as follows
#if defined(BOOST_THREAD_PLATFORM_WIN32) boost::thread::attributes attrs; // set portable attributes attr.set_stack_size(4096*10); // set non portable attribute LPSECURITY_ATTRIBUTES sec; // init sec attr.set_security(sec); boost::thread th(attrs, find_the_question, 42); // Set other thread attributes using the native_handle_type. //... #else #error "Platform not supported" #endif
If the function or callable object passed to the boost::thread
constructor propagates
an exception when invoked that is not of type boost::thread_interrupted
,
std::terminate()
is called.
A thread can be detached by explicitly invoking the detach()
member function on the boost::thread
object. In this case, the
boost::thread
object ceases to represent the now-detached thread, and instead represents
Not-a-Thread.
int main() { boost::thread t(my_func); t.detach(); }
In order to wait for a thread of execution to finish, the join()
,
__join_for or __join_until ( timed_join()
deprecated) member functions of the boost::thread
object must be used. join()
will block the calling thread
until the thread represented by the boost::thread
object has completed.
int main() { boost::thread t(my_func); t.join(); }
If the thread of execution represented by the boost::thread
object has already completed,
or the boost::thread
object represents Not-a-Thread, then join()
returns immediately.
int main() { boost::thread t; t.join(); // do nothing }
Timed based join are similar, except that a call to __join_for or __join_until will also return if the thread being waited for does not complete when the specified time has elapsed or reached respectively.
int main() { boost::thread t; if ( t.join_for(boost::chrono::milliseconds(500)) ) // do something else t.join(); // join anyway }
When the boost::thread
object that represents
a thread of execution is destroyed the thread becomes detached.
Once a thread is detached, it will continue executing until the invocation
of the function or callable object supplied on construction has completed,
or the program is terminated. A thread can also be detached by explicitly
invoking the detach()
member function on the boost::thread
object. In this case, the
boost::thread
object ceases to represent the now-detached thread, and instead represents
Not-a-Thread.
When the boost::thread
object that represents
a thread of execution is destroyed the program terminates if the thread
is __joinable__.
int main() { boost::thread t(my_func); } // calls std::terminate()
You can use a thread_joiner to ensure that the thread has been joined at the thread destructor.
int main() { boost::thread t(my_func); boost::thread_joiner g(t); // do someting else } // here the thread_joiner destructor will join the thread before it is destroyed.
A running thread can be interrupted by invoking the
interrupt()
member function of the corresponding boost::thread
object. When the interrupted
thread next executes one of the specified interruption
points (or if it is currently blocked
whilst executing one) with interruption enabled, then a boost::thread_interrupted
exception will be thrown in the interrupted thread. If not caught, this
will cause the execution of the interrupted thread to terminate. As with
any other exception, the stack will be unwound, and destructors for objects
of automatic storage duration will be executed.
If a thread wishes to avoid being interrupted, it can create an instance
of boost::this_thread::disable_interruption
. Objects
of this class disable interruption for the thread that created them on
construction, and restore the interruption state to whatever it was before
on destruction:
void f() { // interruption enabled here { boost::this_thread::disable_interruption di; // interruption disabled { boost::this_thread::disable_interruption di2; // interruption still disabled } // di2 destroyed, interruption state restored // interruption still disabled } // di destroyed, interruption state restored // interruption now enabled }
The effects of an instance of boost::this_thread::disable_interruption
can be temporarily
reversed by constructing an instance of boost::this_thread::restore_interruption
, passing
in the boost::this_thread::disable_interruption
object in
question. This will restore the interruption state to what it was when
the boost::this_thread::disable_interruption
object was
constructed, and then disable interruption again when the boost::this_thread::restore_interruption
object is
destroyed.
void g() { // interruption enabled here { boost::this_thread::disable_interruption di; // interruption disabled { boost::this_thread::restore_interruption ri(di); // interruption now enabled } // ri destroyed, interruption disable again } // di destroyed, interruption state restored // interruption now enabled }
At any point, the interruption state for the current thread can be queried
by calling boost::this_thread::interruption_enabled()
.
The following functions are interruption points, which
will throw boost::thread_interrupted
if interruption is
enabled for the current thread, and interruption is requested for the current
thread:
boost::thread::join()
boost::thread::timed_join()
boost::thread
::try_join_for
()
,
boost::thread
::try_join_until
()
,
boost::condition_variable::wait()
boost::condition_variable::timed_wait()
boost::condition_variable
::wait_for
()
boost::condition_variable
::wait_until
()
boost::condition_variable_any::wait()
boost::condition_variable_any::timed_wait()
boost::condition_variable_any
::wait_for
()
boost::condition_variable_any
::wait_until
()
boost::thread::sleep()
boost::this_thread::sleep_for
()
boost::this_thread::sleep_until
()
boost::this_thread::interruption_point()
Objects of class boost::thread::id
can be used to identify threads.
Each running thread of execution has a unique ID obtainable from the corresponding
boost::thread
by calling the get_id()
member function, or by calling boost::this_thread::get_id()
from within the thread. Objects of class
boost::thread::id
can be copied, and used as keys in associative containers: the full range
of comparison operators is provided. Thread IDs can also be written to
an output stream using the stream insertion operator, though the output
format is unspecified.
Each instance of boost::thread::id
either refers to some thread,
or Not-a-Thread. Instances that refer to Not-a-Thread
compare equal to each other, but not equal to any instances that refer
to an actual thread of execution. The comparison operators on boost::thread::id
yield a total order for every
non-equal thread ID.
boost::thread
class has members native_handle_type
and native_handle
providing
access to the underlying native handle.
This native handle can be used to change for example the scheduling.
In general, it is not safe to use this handle with operations that can
conflict with the ones provided by Boost.Thread. An example of bad usage
could be detaching a thread directly as it will not change the internals
of the boost::thread
instance, so for example the joinable function will continue to return
true, while the native thread is no more joinable.
thread t(fct); thread::native_handle_type hnd=t.native_handle(); pthread_detach(hnd); assert(t.joinable());
Any thread of execution created using the native interface is called a native thread in this documentation.
The first example of a native thread of execution is the main thread.
The user can access to some synchronization functions related to the native
current thread using the boost::this_thread
yield
, sleep
,
sleep_for
, sleep_until
, functions.
int main() { // ... boost::this_thread::sleep_for(boost::chrono::milliseconds(10)); // ... }
Of course all the synchronization facilities provided by Boost.Thread are also available on native threads.
The boost::this_thread
interrupt related functions
behave in a degraded mode when called from a thread created using the native
interface, i.e. boost::this_thread::interruption_enabled()
returns false. As consequence the use of boost::this_thread::disable_interruption
and boost::this_thread::restore_interruption
will do nothing
and calls to boost::this_thread::interruption_point()
will be just ignored.
As the single way to interrupt a thread is through a boost::thread
instance, interruption_request()
wiil returns false for the native threads.
pthread_exit
POSIX limitation
pthread_exit
in glibc/NPTL
causes a "forced unwind" that is almost like a C++ exception,
but not quite. On Mac OS X, for example, pthread_exit
unwinds without calling C++ destructors.
This behavior is incompatible with the current Boost.Thread design, so the use of this function in a POSIX thread result in undefined behavior of any Boost.Thread function.
joinable()
join()
timed_join()
DEPRECATEDtry_join_for()
EXTENSIONtry_join_until()
EXTENSIONdetach()
get_id()
interrupt()
EXTENSIONhardware_concurrency()
native_handle()
operator==
DEPRECATEDoperator!=
DEPRECATEDsleep()
DEPRECATEDyield()
DEPRECATEDswap()
swap()
boost::thread::id
boost::thread::attributes
EXTENSION#include <boost/thread/thread.hpp> class thread { public: class attributes; // EXTENSION thread() noexcept; thread(const thread&) = delete; thread& operator=(const thread&) = delete; thread(thread&&) noexcept; thread& operator=(thread&&) noexcept; ~thread(); template <class F> explicit thread(F f); template <class F> thread(F &&f); template <class F,class A1,class A2,...> thread(F f,A1 a1,A2 a2,...); template <class F, class ...Args> explicit thread(F&& f, Args&&... args); template <class F> explicit thread(attributes& attrs, F f); // EXTENSION template <class F> thread(attributes& attrs, F &&f); // EXTENSION template <class F, class ...Args> explicit thread(attributes& attrs, F&& f, Args&&... args); // move support thread(thread && x) noexcept; thread& operator=(thread && x) noexcept; void swap(thread& x) noexcept; class id; id get_id() const noexcept; bool joinable() const noexcept; void join(); template <class Rep, class Period> bool try_join_for(const chrono::duration<Rep, Period>& rel_time); // EXTENSION template <class Clock, class Duration> bool try_join_until(const chrono::time_point<Clock, Duration>& t); // EXTENSION void detach(); static unsigned hardware_concurrency() noexcept; typedef platform-specific-type native_handle_type; native_handle_type native_handle(); void interrupt(); // EXTENSION bool interruption_requested() const noexcept; // EXTENSION #if defined BOOST_THREAD_USES_DATETIME bool timed_join(const system_time& wait_until); // DEPRECATED template<typename TimeDuration> bool timed_join(TimeDuration const& rel_time); // DEPRECATED static void sleep(const system_time& xt);// DEPRECATED #endif #if defined BOOST_THREAD_PROVIDES_THREAD_EQ bool operator==(const thread& other) const; // DEPRECATED bool operator!=(const thread& other) const; // DEPRECATED #endif static void yield() noexcept; // DEPRECATED }; void swap(thread& lhs,thread& rhs) noexcept;
thread() noexcept;
Constructs a boost::thread
instance that refers
to Not-a-Thread.
this->get_id()==thread::id()
Nothing
thread(thread&& other) noexcept;
Transfers ownership of the thread managed by other
(if any) to the newly constructed boost::thread
instance.
other.get_id()==thread::id()
and get_id()
returns the value of other.get_id()
prior to the construction
Nothing
thread& operator=(thread&& other) noexcept;
Warning | |
---|---|
DEPRECATED since 3.0.0: BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE behavior. Available only up to Boost 1.56. Join the thread before moving. |
Transfers ownership of the thread managed by other
(if any) to *this
.
- if defined BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE:
If there was a thread previously associated with *this
then that thread is detached,
DEPRECATED
- if defined BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls to std::terminate.
other->get_id()==thread::id()
and get_id()
returns the value of other.get_id()
prior to the assignment.
Nothing
template<typename Callable> thread(Callable func);
Callable
must by
Copyable and func()
must be a valid expression.
func
is copied into
storage managed internally by the thread library, and that copy is
invoked on a newly-created thread of execution. If this invocation
results in an exception being propagated into the internals of the
thread library that is not of type boost::thread_interrupted
,
then std::terminate()
will be called. Any return value from this invocation is ignored.
*this
refers to the newly created thread of execution and this->get_id()!=thread::id()
.
boost::thread_resource_error
if an error
occurs.
resource_unavailable_try_again : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
template<typename Callable> thread(attributes& attrs, Callable func);
Callable
must by
copyable.
func
is copied into
storage managed internally by the thread library, and that copy is
invoked on a newly-created thread of execution with the specified
attributes. If this invocation results in an exception being propagated
into the internals of the thread library that is not of type boost::thread_interrupted
, then std::terminate()
will be called. Any return value from this invocation is ignored.
If the attributes declare the native thread as detached, the boost::thread
will be detached.
*this
refers to the newly created thread of execution and this->get_id()!=thread::id()
.
boost::thread_resource_error
if an error
occurs.
resource_unavailable_try_again : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
template<typename Callable> thread(Callable &&func);
Callable
must by
Movable.
func
is moved into
storage managed internally by the thread library, and that copy is
invoked on a newly-created thread of execution. If this invocation
results in an exception being propagated into the internals of the
thread library that is not of type boost::thread_interrupted
,
then std::terminate()
will be called. Any return value from this invocation is ignored.
*this
refers to the newly created thread of execution and this->get_id()!=thread::id()
.
boost::thread_resource_error
if an error
occurs.
resource_unavailable_try_again : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
template<typename Callable> thread(attributes& attrs, Callable func);
Callable
must by
copyable.
func
is copied into
storage managed internally by the thread library, and that copy is
invoked on a newly-created thread of execution with the specified
attributes. If this invocation results in an exception being propagated
into the internals of the thread library that is not of type boost::thread_interrupted
, then std::terminate()
will be called. Any return value from this invocation is ignored.
If the attributes declare the native thread as detached, the boost::thread
will be detached.
*this
refers to the newly created thread of execution and this->get_id()!=thread::id()
.
boost::thread_resource_error
if an error
occurs.
resource_unavailable_try_again : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
template <class F,class A1,class A2,...> thread(F f,A1 a1,A2 a2,...);
F
and each A
n must by copyable or movable.
*this
refers to the newly created thread of execution.
boost::thread_resource_error
if an error
occurs.
resource_unavailable_try_again : the system lacked the necessary resources to create an- other thread, or the system-imposed limit on the number of threads in a process would be exceeded.
Currently up to nine additional arguments a1
to a9
can be specified
in addition to the function f
.
~thread();
Warning | |
---|---|
DEPRECATED since 3.0.0: BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE behavior. Available only up to Boost 1.56. Join the thread before destroying or use a scoped thread. |
- if defined BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE:
If *this
has an associated thread of execution, calls detach()
,
DEPRECATED
- BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE:
If the thread is joinable calls to std::terminate. Destroys *this
.
Nothing.
Either implicitly detaching or joining a joinable()
thread in its destructor could
result in difficult to debug correctness (for detach
)
or performance (for join
)
bugs encountered only when an exception is raised. Thus the programmer
must ensure that the destructor is never executed while the thread
is still joinable.
bool joinable() const noexcept;
true
if *this
refers to a thread of execution, false
otherwise.
Nothing
void join();
the thread is joinable.
If *this
refers to a thread of execution, waits for that thread of execution
to complete.
The completion of the thread represented by *this
synchronizes with the corresponding
successful join()
return.
Operations on *this are not synchronized.
If *this
refers to a thread of execution on entry, that thread of execution
has completed. *this
no longer refers to any thread of execution.
boost::thread_interrupted
if the current
thread of execution is interrupted or system_error
resource_deadlock_would_occur: if
deadlock is detected or this->get_id() == boost::this_thread::get_id()
.
invalid_argument: if the thread
is not joinable and BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED
is defined.
join()
is one of the predefined interruption
points.
bool timed_join(const system_time& wait_until); template<typename TimeDuration> bool timed_join(TimeDuration const& rel_time);
Warning | |
---|---|
DEPRECATED since 3.00. Available only up to Boost 1.56.
Use instead |
the thread is joinable.
If *this
refers to a thread of execution, waits for that thread of execution
to complete, the time wait_until
has been reach or the specified duration rel_time
has elapsed. If *this
doesn't refer to a thread of execution, returns immediately.
true
if *this
refers to a thread of execution on entry, and that thread of execution
has completed before the call times out, false
otherwise.
If *this
refers to a thread of execution on entry, and timed_join
returns true
, that thread
of execution has completed, and *this
no longer refers to any thread
of execution. If this call to timed_join
returns false
, *this
is unchanged.
boost::thread_interrupted
if the current
thread of execution is interrupted or system_error
resource_deadlock_would_occur: if deadlock is detected or this->get_id() == boost::this_thread::get_id().
invalid_argument: if the thread is not joinable and BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED is defined.
timed_join()
is one of the predefined interruption
points.
template <class Rep, class Period> bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
the thread is joinable.
If *this
refers to a thread of execution, waits for that thread of execution
to complete, the specified duration rel_time
has elapsed. If *this
doesn't refer to a thread of execution, returns immediately.
true
if *this
refers to a thread of execution on entry, and that thread of execution
has completed before the call times out, false
otherwise.
If *this
refers to a thread of execution on entry, and try_join_for
returns true
, that thread
of execution has completed, and *this
no longer refers to any thread
of execution. If this call to try_join_for
returns false
, *this
is unchanged.
boost::thread_interrupted
if the current
thread of execution is interrupted or system_error
resource_deadlock_would_occur: if deadlock is detected or this->get_id() == boost::this_thread::get_id().
invalid_argument: if the thread is not joinable and BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED is defined.
try_join_for()
is one of the predefined interruption
points.
template <class Clock, class Duration> bool try_join_until(const chrono::time_point<Clock, Duration>& abs_time);
the thread is joinable.
If *this
refers to a thread of execution, waits for that thread of execution
to complete, the time abs_time
has been reach. If *this
doesn't refer to a thread of
execution, returns immediately.
true
if *this
refers to a thread of execution on entry, and that thread of execution
has completed before the call times out, false
otherwise.
If *this
refers to a thread of execution on entry, and try_join_until
returns true
, that thread
of execution has completed, and *this
no longer refers to any thread
of execution. If this call to try_join_until
returns false
, *this
is unchanged.
boost::thread_interrupted
if the current
thread of execution is interrupted or system_error
resource_deadlock_would_occur: if deadlock is detected or this->get_id() == boost::this_thread::get_id().
invalid_argument: if the thread is not joinable and BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED is defined.
try_join_until()
is one of the predefined interruption
points.
void detach();
the thread is joinable.
The thread of execution becomes detached, and no longer has an associated
boost::thread
object.
*this
no longer refers to any thread of execution.
system_error
no_such_process: if the thread is not valid.
invalid_argument: if the thread is not joinable and BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED is defined.
thread::id get_id() const noexcept;
If *this
refers to a thread of execution, an instance of boost::thread::id
that represents that
thread. Otherwise returns a default-constructed boost::thread::id
.
Nothing
void interrupt();
If *this
refers to a thread of execution, request that the thread will be
interrupted the next time it enters one of the predefined interruption
points with interruption enabled, or if it is currently
blocked in a call to one of the predefined
interruption points
with interruption enabled .
Nothing
unsigned hardware_concurrency() noexecpt;
The number of hardware threads available on the current system (e.g. number of CPUs or cores or hyperthreading units), or 0 if this information is not available.
Nothing
typedef platform-specific-type native_handle_type; native_handle_type native_handle();
Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the underlying
implementation. If no such instance exists, native_handle()
and native_handle_type
are not present.
Nothing.
bool operator==(const thread& other) const;
Warning | |
---|---|
DEPRECATED since 4.0.0. Available only up to Boost 1.58. |
get_id()==other.get_id()
bool operator!=(const thread& other) const;
Warning | |
---|---|
DEPRECATED since 4.0.0. Available only up to Boost 1.58. |
get_id()!=other.get_id()
void sleep(system_time const& abs_time);
Warning | |
---|---|
DEPRECATED since 3.0.0. Available only up to Boost 1.56.
Use |
Suspends the current thread until the specified time has been reached.
boost::thread_interrupted
if the current
thread of execution is interrupted.
sleep()
is one of the predefined interruption
points.
void yield();
Warning | |
---|---|
DEPRECATED since 3.0.0. Available only up to Boost 1.56.
Use |
void swap(thread& other) noexcept;
Exchanges the threads of execution associated with *this
and other
, so *this
is associated with the thread of execution associated with other
prior to the call, and vice-versa.
this->get_id()
returns the same value as other.get_id()
prior to the call. other.get_id()
returns the same value as this->get_id()
prior to the call.
Nothing.
#include <boost/thread/thread.hpp> void swap(thread& lhs,thread& rhs) noexcept;
#include <boost/thread/thread.hpp> class thread::id { public: id() noexcept; bool operator==(const id& y) const noexcept; bool operator!=(const id& y) const noexcept; bool operator<(const id& y) const noexcept; bool operator>(const id& y) const noexcept; bool operator<=(const id& y) const noexcept; bool operator>=(const id& y) const noexcept; template<class charT, class traits> friend std::basic_ostream<charT, traits>& operator<<(std::basic_ostream<charT, traits>& os, const id& x); };
id() noexcept;
Constructs a boost::thread::id
instance that represents
Not-a-Thread.
Nothing
bool operator==(const id& y) const noexcept;
true
if *this
and y
both represent
the same thread of execution, or both represent Not-a-Thread,
false
otherwise.
Nothing
bool operator!=(const id& y) const noexcept;
true
if *this
and y
represent
different threads of execution, or one represents a thread of execution,
and the other represent Not-a-Thread, false
otherwise.
Nothing
bool operator<(const id& y) const noexcept;
true
if *this!=y
is true
and the implementation-defined
total order of boost::thread::id
values places *this
before y
, false
otherwise.
Nothing
A boost::thread::id
instance representing
Not-a-Thread will always compare less than
an instance representing a thread of execution.
template<class charT, class traits> friend std::basic_ostream<charT, traits>& operator<<(std::basic_ostream<charT, traits>& os, const id& x);
Writes a representation of the boost::thread::id
instance x
to the stream os
, such that the representation
of two instances of boost::thread::id
a
and b
is the same
if a==b
, and different if a!=b
.
os
class thread::attributes { public: attributes() noexcept; ~ attributes()=default; // stack void set_stack_size(std::size_t size) noexcept; std::size_t get_stack_size() const noexcept; #if defined BOOST_THREAD_DEFINES_THREAD_ATTRIBUTES_NATIVE_HANDLE typedef platform-specific-type native_handle_type; native_handle_type* native_handle() noexcept; const native_handle_type* native_handle() const noexcept; #endif };
thread_attributes() noexcept;
Constructs a thread atrributes instance with its default values.
Nothing
void set_stack_size(std::size_t size) noexcept;
Stores the stack size to be used to create a thread. This is an hint that the implementation can choose a better size if to small or too big or not aligned to a page.
this->
get_stack_size()
returns the chosen stack size.
Nothing.
std::size_t get_stack_size() const noexcept;
The stack size to be used on the creation of a thread. Note that this function can return 0 meaning the default.
Nothing.
typedef platform-specific-type native_handle_type; typedef platform-specific-type native_handle_type; native_handle_type* native_handle() noexcept; const native_handle_type* native_handle() const noexcept;
Returns an instance of native_handle_type
that can be used with platform-specific APIs to manipulate the
underlying thread attributes implementation. If no such instance
exists, native_handle()
and native_handle_type
are not present and BOOST_THREAD_DEFINES_THREAD_ATTRIBUTES_NATIVE_HANDLE
is not defined.
Nothing.
get_id()
interruption_point()
EXTENSIONinterruption_requested()
EXTENSIONinterruption_enabled()
EXTENSIONsleep()
DEPRECATEDsleep_until()
sleep_for()
yield()
disable_interruption
EXTENSIONrestore_interruption
EXTENSIONat_thread_exit()
EXTENSIONnamespace boost { namespace this_thread { thread::id get_id() noexcept; template<typename TimeDuration> void yield() noexcept; template <class Clock, class Duration> void sleep_until(const chrono::time_point<Clock, Duration>& abs_time); template <class Rep, class Period> void sleep_for(const chrono::duration<Rep, Period>& rel_time); template<typename Callable> void at_thread_exit(Callable func); // EXTENSION void interruption_point(); // EXTENSION bool interruption_requested() noexcept; // EXTENSION bool interruption_enabled() noexcept; // EXTENSION class disable_interruption; // EXTENSION class restore_interruption; // EXTENSION #if defined BOOST_THREAD_USES_DATETIME void sleep(TimeDuration const& rel_time); // DEPRECATED void sleep(system_time const& abs_time); // DEPRECATED #endif } }
#include <boost/thread/thread.hpp> namespace this_thread { thread::id get_id() noexcept; }
An instance of boost::thread::id
that represents that
currently executing thread.
boost::thread_resource_error
if an error
occurs.
#include <boost/thread/thread.hpp> namespace this_thread { void interruption_point(); }
Check to see if the current thread has been interrupted.
boost::thread_interrupted
if boost::this_thread::interruption_enabled()
and boost::this_thread::interruption_requested()
both return true
.
#include <boost/thread/thread.hpp> namespace this_thread { bool interruption_requested() noexcept; }
true
if interruption
has been requested for the current thread, false
otherwise.
Nothing.
#include <boost/thread/thread.hpp> namespace this_thread { bool interruption_enabled() noexcept; }
true
if interruption
has been enabled for the current thread, false
otherwise.
Nothing.
#include <boost/thread/thread.hpp> namespace this_thread { template<typename TimeDuration> void sleep(TimeDuration const& rel_time); void sleep(system_time const& abs_time) }
Warning | |
---|---|
DEPRECATED since 3.0.0. Available only up to Boost 1.56.
Use |
Suspends the current thread until the time period specified by rel_time
has elapsed or the time
point specified by abs_time
has been reached.
boost::thread_interrupted
if the current
thread of execution is interrupted.
sleep()
is one of the predefined interruption
points.
#include <boost/thread/thread.hpp> namespace this_thread { template <class Clock, class Duration> void sleep_until(const chrono::time_point<Clock, Duration>& abs_time); }
Suspends the current thread until the time point specified by abs_time
has been reached.
Nothing if Clock satisfies the TrivialClock requirements and operations
of Duration do not throw exceptions. boost::thread_interrupted
if the current thread of execution is interrupted.
sleep_until()
is one of the predefined interruption
points.
#include <boost/thread/thread.hpp> namespace this_thread { template <class Rep, class Period> void sleep_for(const chrono::duration<Rep, Period>& rel_time); }
Suspends the current thread until the duration specified by by rel_time
has elapsed.
Nothing if operations of chrono::duration<Rep, Period> do not
throw exceptions. boost::thread_interrupted
if the current thread of execution is interrupted.
sleep_for()
is one of the predefined interruption
points.
#include <boost/thread/thread.hpp> namespace this_thread { void yield() noexcept; }
Gives up the remainder of the current thread's time slice, to allow other threads to run.
Nothing.
#include <boost/thread/thread.hpp> namespace this_thread { class disable_interruption { public: disable_interruption(const disable_interruption&) = delete; disable_interruption& operator=(const disable_interruption&) = delete; disable_interruption() noexcept; ~disable_interruption() noexcept; }; }
boost::this_thread::disable_interruption
disables interruption
for the current thread on construction, and restores the prior interruption
state on destruction. Instances of disable_interruption
cannot be copied or moved.
disable_interruption() noexcept;
Stores the current state of boost::this_thread::interruption_enabled()
and disables interruption for the current thread.
boost::this_thread::interruption_enabled()
returns false
for
the current thread.
Nothing.
~disable_interruption() noexcept;
Must be called from the same thread from which *this
was constructed.
Restores the current state of boost::this_thread::interruption_enabled()
for the current thread to that prior to the construction of *this
.
boost::this_thread::interruption_enabled()
for the current thread returns the value stored in the constructor
of *this
.
Nothing.
#include <boost/thread/thread.hpp> namespace this_thread { class restore_interruption { public: restore_interruption(const restore_interruption&) = delete; restore_interruption& operator=(const restore_interruption&) = delete; explicit restore_interruption(disable_interruption& disabler) noexcept; ~restore_interruption() noexcept; }; }
On construction of an instance of boost::this_thread::restore_interruption
,
the interruption state for the current thread is restored to the interruption
state stored by the constructor of the supplied instance of boost::this_thread::disable_interruption
. When the
instance is destroyed, interruption is again disabled. Instances of restore_interruption
cannot be copied
or moved.
explicit restore_interruption(disable_interruption& disabler) noexcept;
Must be called from the same thread from which disabler
was constructed.
Restores the current state of boost::this_thread::interruption_enabled()
for the current thread to that prior to the construction of disabler
.
boost::this_thread::interruption_enabled()
for the current thread returns the value stored in the constructor
of disabler
.
Nothing.
~restore_interruption() noexcept;
Must be called from the same thread from which *this
was constructed.
Disables interruption for the current thread.
boost::this_thread::interruption_enabled()
for the current thread returns false
.
Nothing.
#include <boost/thread/thread.hpp> template<typename Callable> void at_thread_exit(Callable func);
A copy of func
is
placed in thread-specific storage. This copy is invoked when the
current thread exits (even if the thread has been interrupted).
A copy of func
has
been saved for invocation on thread exit.
std::bad_alloc
if memory cannot be allocated
for the copy of the function, boost::thread_resource_error
if any other error occurs within the thread library. Any exception
thrown whilst copying func
into internal storage.
This function is not called if the
thread was terminated forcefully using platform-specific APIs, or
if the thread is terminated due to a call to exit()
, abort()
or std::terminate()
. In particular, returning from
main()
is equivalent to call to exit()
, so will not call any functions
registered with at_thread_exit()
#include <boost/thread/thread.hpp> #include <boost/thread/thread_group.hpp> class thread_group { public: thread_group(const thread_group&) = delete; thread_group& operator=(const thread_group&) = delete; thread_group(); ~thread_group(); template<typename F> thread* create_thread(F threadfunc); void add_thread(thread* thrd); void remove_thread(thread* thrd); bool is_this_thread_in(); bool is_thread_in(thread* thrd); void join_all(); void interrupt_all(); int size() const; };
thread_group
provides for
a collection of threads that are related in some fashion. New threads can
be added to the group with add_thread
and create_thread
member
functions. thread_group
is
not copyable or movable.
~thread_group();
Destroy *this
and delete
all boost::thread
objects in the group.
template<typename F> thread* create_thread(F threadfunc);
Create a new boost::thread
object as-if by
new thread(threadfunc)
and add it to the group.
this->size()
is increased by one, the new thread is running.
A pointer to the new boost::thread
object.
void add_thread(thread* thrd);
The expression delete thrd
is well-formed and will not
result in undefined behaviour and is_thread_in(thrd) == false
.
Take ownership of the boost::thread
object pointed to
by thrd
and add it
to the group.
this->size()
is increased by one.
void remove_thread(thread* thrd);
If thrd
is a member
of the group, remove it without calling delete
.
If thrd
was a member
of the group, this->size()
is decreased by one.
void join_all();
is_this_thread_in() == false
.
Call join()
on each boost::thread
object in the group.
Every thread in the group has terminated.
Since join()
is one of the predefined interruption
points, join_all()
is also an interruption point.
bool is_this_thread_in();
true if there is a thread th
in the group such that th.get_id() == this_thread::get_id()
.
bool is_thread_in(thread* thrd);
true if there is a thread th
in the group such that th.get_id() == thrd->get_id()
.
void interrupt_all();
Call interrupt()
on each boost::thread
object in the group.