Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Class thread

Default Constructor
Move Constructor
Move assignment operator
Thread Constructor
Thread Attributes Constructor EXTENSION
Thread Callable Move Constructor
Thread Attributes Move Constructor EXTENSION
Thread Constructor with arguments
Thread Destructor
Member function joinable()
Member function join()
Member function timed_join() DEPRECATED
Member function try_join_for() EXTENSION
Member function try_join_until() EXTENSION
Member function detach()
Member function get_id()
Member function interrupt() EXTENSION
Static member function hardware_concurrency()
Static member function physical_concurrency()
Member function native_handle()
operator== DEPRECATED
operator!= DEPRECATED
Static member function sleep() DEPRECATED
Static member function yield() DEPRECATED
Member function swap()
Non-member function swap()
Class boost::thread::id
Default constructor
operator==
operator!=
operator<
operator>
operator<=
operator>=
Friend operator<<
Class boost::thread::attributes EXTENSION
Default constructor
Member function set_stack_size()
Member function get_stack_size()
Member function native_handle()
#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;
thread() noexcept;

Effects:

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

Postconditions:

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

Throws:

Nothing

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

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

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.

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.

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.

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.

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

Preconditions:

F and each An must be copyable or movable.

Effects:

As if thread(boost::bind(f,a1,a2,...)). Consequently, f and each an 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();

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.

bool joinable() const noexcept;

Returns:

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

Throws:

Nothing

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.

bool timed_join(const system_time& wait_until);

template<typename TimeDuration>
bool timed_join(TimeDuration const& rel_time);
[Warning] 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.

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.

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.

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.

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

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

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

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

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.

bool operator==(const thread& other) const;
[Warning] Warning

DEPRECATED since 4.0.0.

Use a.get_id()==b.get_id() instead`.

Returns:

get_id()==other.get_id()

bool operator!=(const thread& other) const;
[Warning] Warning

DEPRECATED since 4.0.0.

Use a.get_id()!=b.get_id() instead`.

Returns:

get_id()!=other.get_id()

void sleep(system_time const& abs_time);
[Warning] 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.

void yield();
[Warning] Warning

DEPRECATED since 3.0.0.

Use this_thread::yield().

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.

#include <boost/thread/thread.hpp>

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

Effects:

lhs.swap(rhs).

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

Effects:

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

Throws:

Nothing

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

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

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.

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

Returns:

y<*this

Throws:

Nothing

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

Returns:

!(y<*this)

Throws:

Nothing

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

Returns:

!(*this<y)

Throws:

Nothing

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

Effects:

Constructs a thread attributes instance with its default values.

Throws:

Nothing

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.

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.

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.


PrevUpHomeNext