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.

[Note: On compilers that support rvalue references, boost::thread
provides a proper move constructor and move-assignment operator, and therefore
meets the C++0x MoveConstructible and MoveAssignable
concepts. With such compilers, boost::thread
can therefore be used with containers that support those concepts.

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.

structcallable{voidoperator()();};boost::threadcopies_are_safe(){callablex;returnboost::thread(x);}// x is destroyed, but the newly-created thread has a copy, so this is OK
boost::threadoops(){callablex;returnboost::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:

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.

In order to wait for a thread of execution to finish, the join()
or timed_join()
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. 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. timed_join()
is similar, except that a call to timed_join()
will also return if the thread being waited for does not complete when the
specified time has elapsed.

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:

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.

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.

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.

Returns:

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.

Postconditions:

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.

Throws:

boost::thread_interrupted if the current
thread of execution is interrupted.

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 .

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.

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.

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.

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).

Postconditions:

A copy of func has
been saved for invocation on thread exit.

Throws:

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.

Note:

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()

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.