Thread Management

| Home | Libraries | People | FAQ | More

## Thread Management

### Synopsis

    #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;
        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);
        namespace no_interruption_point  // EXTENSION
        {
        	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

    }

### Tutorial

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, `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.

#### Launching threads

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 attributes

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

#### Exceptions in thread functions

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.

#### Detaching thread

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

#### Joining a thread

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
    }

#### Destructor V1-2

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.

#### Destructor V3-X

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 something else
    } // here the thread_joiner destructor will join the thread before it is destroyed.

#### Interruption

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

###### Predefined Interruption Points

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

#### Thread IDs

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.

#### Using native interfaces with Boost.Thread resources

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

#### Using Boost.Thread interfaces in a native thread

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()` will return 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.

### Class `thread`

    #include <boost/thread/thread.hpp>

    class thread
    {
    public:
        class attributes; // EXTENSION

        thread() noexcept;
        ~thread();

        thread(const thread&) = delete;
        thread& operator=(const thread&) = delete;

        // move support
        thread(thread&&) noexcept;
        thread& operator=(thread&&) noexcept;

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

        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;
        static unsigned physical_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;

#### Default Constructor

    thread() noexcept;

Effects:

  Constructs a `boost::thread` instance that refers to Not-a-Thread.

Postconditions:

  `this->get_id()==thread::id()`

Throws:

  Nothing

#### Move Constructor

    thread(thread&& other) noexcept;

Effects:

  Transfers ownership of the thread managed by `other` (if any) to the newly constructed `boost::thread` instance.

Postconditions:

  `other.get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the construction

Throws:

  Nothing

#### Move assignment operator

    thread& operator=(thread&& other) noexcept;

Effects:

  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 the thread is joinable call `detach()`, DEPRECATED

  - if defined BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls to `std::terminate()`.

Postconditions:

  `other->get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.

Throws:

  Nothing

#### Thread Constructor

    template<typename Callable>
    thread(Callable func);

Requires:

  `Callable` must be Copyable and `func()` must be a valid expression.

Effects:

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

Postconditions:

  `*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  `boost::thread_resource_error` if an error occurs.

Error Conditions:

  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.

#### Thread Attributes Constructor EXTENSION

    template<typename Callable>
    thread(attributes& attrs, Callable func);

Preconditions:

  `Callable` must be copyable.

Effects:

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

Postconditions:

  `*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  `boost::thread_resource_error` if an error occurs.

Error Conditions:

  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.

#### Thread Callable Move Constructor

    template<typename Callable>
    thread(Callable &&func);

Preconditions:

  `Callable` must be Movable.

Effects:

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

Postconditions:

  `*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  `boost::thread_resource_error` if an error occurs.

Error Conditions:

  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.

#### Thread Attributes Move Constructor EXTENSION

    template<typename Callable>
    thread(attributes& attrs, Callable func);

Preconditions:

  `Callable` must be copyable.

Effects:

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

Postconditions:

  `*this` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  `boost::thread_resource_error` if an error occurs.

Error Conditions:

  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.

#### Thread Constructor with arguments

    template <class F,class A1,class A2,...>
    thread(F f,A1 a1,A2 a2,...);

Preconditions:

  `F` and each `A`n must be copyable or movable.

Effects:

  As if `thread(boost::bind(f,a1,a2,...))`. Consequently, `f` and each `a`n are copied into internal storage for access by the new thread.

Postconditions:

  `*this` refers to the newly created thread of execution.

Throws:

  `boost::thread_resource_error` if an error occurs.

Error Conditions:

  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.

Note:

  Currently up to nine additional arguments `a1` to `a9` can be specified in addition to the function `f`.

#### Thread Destructor

    ~thread();

Effects:

  - if defined BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls `detach()`, DEPRECATED

  - if defined BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls to `std::terminate`. Destroys `*this`.

Throws:

  Nothing.

Note:

  The reason to moving to std::terminate is that 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. Join the thread before destroying or use a scoped thread.

#### Member function `joinable()`

    bool joinable() const noexcept;

Returns:

  `true` if `*this` refers to a thread of execution, `false` otherwise.

Throws:

  Nothing

#### Member function `join()`

    void join();

Preconditions:

  the thread is joinable.

Effects:

  If `*this` refers to a thread of execution, waits for that thread of execution to complete.

Synchronization:

  The completion of the thread represented by `*this` synchronizes with the corresponding successful `join()` return.

Note:

  Operations on *this are not synchronized.

Postconditions:

  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.

Throws:

  `boost::thread_interrupted` if the current thread of execution is interrupted or `system_error`

Error Conditions:

  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_THROW_IF_PRECONDITION_NOT_SATISFIED` is defined.

Notes:

  `join()` is one of the predefined interruption points.

#### Member function `timed_join()` DEPRECATED

    bool timed_join(const system_time& wait_until);

    template<typename TimeDuration>
    bool timed_join(TimeDuration const& rel_time);

| Warning
DEPRECATED since 3.00. Use instead `try_join_for`, `try_join_until`.

Preconditions:

  the thread is joinable.

Effects:

  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 or `system_error`

Error Conditions:

  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_THROW_IF_PRECONDITION_NOT_SATISFIED is defined.

Notes:

  `timed_join()` is one of the predefined interruption points.

#### Member function `try_join_for()` EXTENSION

    template <class Rep, class Period>
    bool try_join_for(const chrono::duration<Rep, Period>& rel_time);

Preconditions:

  the thread is joinable.

Effects:

  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.

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

Throws:

  `boost::thread_interrupted` if the current thread of execution is interrupted or `system_error`

Error Conditions:

  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_THROW_IF_PRECONDITION_NOT_SATISFIED is defined.

Notes:

  `try_join_for()` is one of the predefined interruption points.

#### Member function `try_join_until()` EXTENSION

    template <class Clock, class Duration>
    bool try_join_until(const chrono::time_point<Clock, Duration>& abs_time);

Preconditions:

  the thread is joinable.

Effects:

  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.

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

Throws:

  `boost::thread_interrupted` if the current thread of execution is interrupted or `system_error`

Error Conditions:

  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_THROW_IF_PRECONDITION_NOT_SATISFIED is defined.

Notes:

  `try_join_until()` is one of the predefined interruption points.

#### Member function `detach()`

    void detach();

Preconditions:

  the thread is joinable.

Effects:

  The thread of execution becomes detached, and no longer has an associated `boost::thread` object.

Postconditions:

  `*this` no longer refers to any thread of execution.

Throws:

  `system_error`

Error Conditions:

  no_such_process: if the thread is not valid.

  invalid_argument: if the thread is not joinable and BOOST_THREAD_THROW_IF_PRECONDITION_NOT_SATISFIED is defined.

#### Member function `get_id()`

    thread::id get_id() const noexcept;

Returns:

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

Throws:

  Nothing

#### Member function `interrupt()` EXTENSION

    void interrupt();

Effects:

  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 .

Throws:

  Nothing

#### Static member function `hardware_concurrency()`

    unsigned hardware_concurrency() noexcept;

Returns:

  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.

Throws:

  Nothing

#### Static member function `physical_concurrency()`

    unsigned physical_concurrency() noexcept;

Returns:

  The number of physical cores available on the current system. In contrast to `hardware_concurrency()` it does not return the number of virtual cores, but it counts only physical cores.

Throws:

  Nothing

#### Member function `native_handle()`

    typedef platform-specific-type native_handle_type;
    native_handle_type native_handle();

Effects:

  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.

Throws:

  Nothing.

#### `operator==` DEPRECATED

    bool operator==(const thread& other) const;

| Warning
DEPRECATED since 4.0.0. Use `a.`get_id`()==b.`get_id`()` instead`.

Returns:

  `get_id()==other.get_id()`

#### `operator!=` DEPRECATED

    bool operator!=(const thread& other) const;

| Warning
DEPRECATED since 4.0.0. Use `a.`get_id`()!=b.`get_id`()` instead`.

Returns:

  `get_id()!=other.get_id()`

#### Static member function `sleep()` DEPRECATED

    void sleep(system_time const& abs_time);

| Warning
DEPRECATED since 3.0.0. Use `this_thread::`sleep_for`()` or `this_thread::`sleep_until`()`.

Effects:

  Suspends the current thread until the specified time has been reached.

Throws:

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

Notes:

  `sleep()` is one of the predefined interruption points.

#### Static member function `yield()` DEPRECATED

    void yield();

| Warning
DEPRECATED since 3.0.0. Use `this_thread::`yield`()`.

Effects:

  See `boost::this_thread::yield()`.

#### Member function `swap()`

    void swap(thread& other) noexcept;

Effects:

  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.

Postconditions:

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

Throws:

  Nothing.

#### Non-member function `swap()`

    #include <boost/thread/thread.hpp>

    void swap(thread& lhs,thread& rhs) noexcept;

Effects:

  `lhs.swap(rhs)`.

#### Class `boost::thread::id`

    #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);
    };

##### Default constructor

    id() noexcept;

Effects:

  Constructs a `boost::thread::id` instance that represents Not-a-Thread.

Throws:

  Nothing

##### `operator==`

    bool operator==(const id& y) const noexcept;

Returns:

  `true` if `*this` and `y` both represent the same thread of execution, or both represent Not-a-Thread, `false` otherwise.

Throws:

  Nothing

##### `operator!=`

    bool operator!=(const id& y) const noexcept;

Returns:

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

Throws:

  Nothing

##### `operator<`

    bool operator<(const id& y) const noexcept;

Returns:

  `true` if `*this!=y` is `true` and the implementation-defined total order of `boost::thread::id` values places `*this` before `y`, `false` otherwise.

Throws:

  Nothing

Note:

  A `boost::thread::id` instance representing Not-a-Thread will always compare less than an instance representing a thread of execution.

##### `operator>`

    bool operator>(const id& y) const noexcept;

Returns:

  `y<*this`

Throws:

  Nothing

##### `operator<=`

    bool operator<=(const id& y) const noexcept;

Returns:

  `!(y<*this)`

Throws:

  Nothing

##### `operator>=`

    bool operator>=(const id& y) const noexcept;

Returns:

  `!(*this<y)`

Throws:

  Nothing

##### Friend `operator<<`

    template<class charT, class traits>
    friend std::basic_ostream<charT, traits>&
    operator<<(std::basic_ostream<charT, traits>& os, const id& x);

Effects:

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

Returns:

  `os`

#### Class `boost::thread::attributes` EXTENSION

    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

    };

##### Default constructor

    thread_attributes() noexcept;

Effects:

  Constructs a thread attributes instance with its default values.

Throws:

  Nothing

##### Member function `set_stack_size()`

    void set_stack_size(std::size_t size) noexcept;

Effects:

  Stores the stack size to be used to create a thread. This is a hint that the implementation can choose a better size if to small or too big or not aligned to a page.

Postconditions:

  `this-> get_stack_size()` returns the chosen stack size.

Throws:

  Nothing.

##### Member function `get_stack_size()`

    std::size_t get_stack_size() const noexcept;

Returns:

  The stack size to be used on the creation of a thread. Note that this function can return 0 meaning the default.

Throws:

  Nothing.

##### Member function `native_handle()`

    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;

Effects:

  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.

Throws:

  Nothing.

### Namespace `this_thread`

    namespace 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
      }
    }

#### Non-member function `get_id()`

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        thread::id get_id() noexcept;
    }

Returns:

  An instance of `boost::thread::id` that represents that currently executing thread.

Throws:

  `boost::thread_resource_error` if an error occurs.

#### Non-member function `interruption_point()` EXTENSION

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        void interruption_point();
    }

Effects:

  Check to see if the current thread has been interrupted.

Throws:

  `boost::thread_interrupted` if `boost::this_thread::interruption_enabled()` and `boost::this_thread::interruption_requested()` both return `true`.

#### Non-member function `interruption_requested()` EXTENSION

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        bool interruption_requested() noexcept;
    }

Returns:

  `true` if interruption has been requested for the current thread, `false` otherwise.

Throws:

  Nothing.

#### Non-member function `interruption_enabled()` EXTENSION

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        bool interruption_enabled() noexcept;
    }

Returns:

  `true` if interruption has been enabled for the current thread, `false` otherwise.

Throws:

  Nothing.

#### Non-member function `sleep()` DEPRECATED

    #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. Use ``sleep_for`()` and ``sleep_until`()` instead.

Effects:

  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.

Throws:

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

Notes:

  `sleep()` is one of the predefined interruption points.

#### Non-member function `sleep_until()`

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
      template <class Clock, class Duration>
      void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
      namespace no_interruption_point
      {
        template <class Clock, class Duration>
        void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
      }
    }

Effects:

  Suspends the current thread until the time point specified by `abs_time` has been reached.

Throws:

  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.

Notes:

  `sleep_until()` is one of the predefined interruption points.

Notes:

  `no_interruption_point::sleep_until()` is NOT one of the interruption points.

#### Non-member function `sleep_for()`

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
      template <class Rep, class Period>
      void sleep_for(const chrono::duration<Rep, Period>& rel_time);
      namespace no_interruption_point
      {
        template <class Rep, class Period>
        void sleep_for(const chrono::duration<Rep, Period>& rel_time);
      }
    }

Effects:

  Suspends the current thread until the duration specified by `rel_time` has elapsed.

Throws:

  Nothing if operations of chrono::duration<Rep, Period> do not throw exceptions. `boost::thread_interrupted` if the current thread of execution is interrupted.

Notes:

  `sleep_for()` is one of the predefined interruption points.

Notes:

  `no_interruption_point:: sleep_for()` is NOT one of the interruption points.

#### Non-member function `yield()`

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        void yield() noexcept;
    }

Effects:

  Gives up the remainder of the current thread's time slice, to allow other threads to run.

Throws:

  Nothing.

#### Class `disable_interruption` EXTENSION

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

##### Constructor

    disable_interruption() noexcept;

Effects:

  Stores the current state of `boost::this_thread::interruption_enabled()` and disables interruption for the current thread.

Postconditions:

  `boost::this_thread::interruption_enabled()` returns `false` for the current thread.

Throws:

  Nothing.

##### Destructor

    ~disable_interruption() noexcept;

Preconditions:

  Must be called from the same thread from which `*this` was constructed.

Effects:

  Restores the current state of `boost::this_thread::interruption_enabled()` for the current thread to that prior to the construction of `*this`.

Postconditions:

  `boost::this_thread::interruption_enabled()` for the current thread returns the value stored in the constructor of `*this`.

Throws:

  Nothing.

#### Class `restore_interruption` EXTENSION

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

##### Constructor

    explicit restore_interruption(disable_interruption& disabler) noexcept;

Preconditions:

  Must be called from the same thread from which `disabler` was constructed.

Effects:

  Restores the current state of `boost::this_thread::interruption_enabled()` for the current thread to that prior to the construction of `disabler`.

Postconditions:

  `boost::this_thread::interruption_enabled()` for the current thread returns the value stored in the constructor of `disabler`.

Throws:

  Nothing.

##### Destructor

    ~restore_interruption() noexcept;

Preconditions:

  Must be called from the same thread from which `*this` was constructed.

Effects:

  Disables interruption for the current thread.

Postconditions:

  `boost::this_thread::interruption_enabled()` for the current thread returns `false`.

Throws:

  Nothing.

#### Non-member function template `at_thread_exit()` EXTENSION

    #include <boost/thread/thread.hpp>

    template<typename Callable>
    void at_thread_exit(Callable func);

Effects:

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

### Class `thread_group` EXTENSION

    #include <boost/thread/thread.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.

#### Constructor

    thread_group();

Effects:

  Create a new thread group with no threads.

#### Destructor

    ~thread_group();

Effects:

  Destroy `*this` and `delete` all `boost::thread` objects in the group.

#### Member function `create_thread()`

    template<typename F>
    thread* create_thread(F threadfunc);

Effects:

  Create a new `boost::thread` object as-if by `new thread(threadfunc)` and add it to the group.

Postcondition:

  `this->size()` is increased by one, the new thread is running.

Returns:

  A pointer to the new `boost::thread` object.

#### Member function `add_thread()`

    void add_thread(thread* thrd);

Precondition:

  The expression `delete thrd` is well-formed and will not result in undefined behaviour and `is_thread_in(thrd) == false`.

Effects:

  Take ownership of the `boost::thread` object pointed to by `thrd` and add it to the group.

Postcondition:

  `this->size()` is increased by one.

#### Member function `remove_thread()`

    void remove_thread(thread* thrd);

Effects:

  If `thrd` is a member of the group, remove it without calling `delete`.

Postcondition:

  If `thrd` was a member of the group, `this->size()` is decreased by one.

#### Member function `join_all()`

    void join_all();

Requires:

  `is_this_thread_in() == false`.

Effects:

  Call `join()` on each `boost::thread` object in the group.

Postcondition:

  Every thread in the group has terminated.

Note:

  Since `join()` is one of the predefined interruption points, `join_all()` is also an interruption point.

#### Member function `is_this_thread_in()`

    bool is_this_thread_in();

Returns:

  true if there is a thread `th` in the group such that `th.get_id() == this_thread::get_id()`.

#### Member function `is_thread_in()`

    bool is_thread_in(thread* thrd);

Returns:

  true if there is a thread `th` in the group such that `th.get_id() == thrd->get_id()`.

#### Member function `interrupt_all()`

    void interrupt_all();

Effects:

  Call `interrupt()` on each `boost::thread` object in the group.

#### Member function `size()`

    int size();

Returns:

  The number of threads in the group.

Throws:

  Nothing.