path: root/libs/thread/doc/thread_ref.qbk

[/
  (C) Copyright 2007-8 Anthony Williams.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:thread_management Thread Management]

[heading Synopsis]

The __thread__ class is responsible for launching and managing threads. Each __thread__ object represents a single thread of execution,
or __not_a_thread__, and at most one __thread__ object represents a given thread of execution: objects of type __thread__ are not
copyable.

Objects of type __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, __thread__ provides a proper move constructor and move-assignment operator, and
therefore meets the C++0x ['MoveConstructible] and ['MoveAssignable] concepts. With such compilers, __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.]

[heading 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 __thread__ with a function or callable object that requires arguments to be supplied,
this can be done by passing additional arguments to the __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.

[heading Exceptions in thread functions]

If the function or callable object passed to the __thread__ constructor propagates an exception when invoked that is not of type
__thread_interrupted__, `std::terminate()` is called. 

[heading Joining and detaching]

When the __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 __thread__
object. In this case, the __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 __thread__ object must be
used. __join__ will block the calling thread until the thread represented by the __thread__ object has completed. If the thread of
execution represented by the __thread__ object has already completed, or the __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.

[heading Interruption]

A running thread can be ['interrupted] by invoking the __interrupt__ member function of the corresponding __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 __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 __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 __disable_interruption__ can be temporarily reversed by constructing an instance of
__restore_interruption__, passing in the __disable_interruption__ object in question. This will
restore the interruption state to what it was when the __disable_interruption__ object was constructed, and then
disable interruption again when the __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 __interruption_enabled__.

[#interruption_points]

[heading Predefined Interruption Points]

The following functions are ['interruption points], which will throw __thread_interrupted__ if interruption is enabled for the
current thread, and interruption is requested for the current thread:

* [join_link `boost::thread::join()`]
* [timed_join_link `boost::thread::timed_join()`]
* [cond_wait_link `boost::condition_variable::wait()`]
* [cond_timed_wait_link `boost::condition_variable::timed_wait()`]
* [cond_any_wait_link `boost::condition_variable_any::wait()`]
* [cond_any_timed_wait_link `boost::condition_variable_any::timed_wait()`]
* [link thread.thread_management.thread.sleep `boost::thread::sleep()`]
* __sleep__
* __interruption_point__

[heading Thread IDs]

Objects of class __thread_id__ can be used to identify threads. Each running thread of execution has a unique ID obtainable
from the corresponding __thread__ by calling the `get_id()` member function, or by calling `boost::this_thread::get_id()` from
within the thread. Objects of class __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 __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
__thread_id__ yield a total order for every non-equal thread ID.

[heading Using native interfaces with Boost.Thread resources] 


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

[heading 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`, functions. 


  int main() { 
    // ... 
    boost::this_thread::sleep(); 
    // ... 
  } 


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::interrupt_point()` will be just ignored.  

As the single way to interrupt a thread is through a __thread__ instance, `interruption_request()` wiil returns false for the native threads. 

[section:thread Class `thread`]

    #include <boost/thread/thread.hpp>

    class thread
    {
    public:
        thread();
        ~thread();

        template <class F>
        explicit thread(F f);

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

        template <class F>
        thread(detail::thread_move_t<F> f);

        // move support
        thread(detail::thread_move_t<thread> x);
        thread& operator=(detail::thread_move_t<thread> x);
        operator detail::thread_move_t<thread>();
        detail::thread_move_t<thread> move();

        void swap(thread& x);

        class id;
        id get_id() const;

        bool joinable() const;
        void join();
        bool timed_join(const system_time& wait_until);

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

        void detach();

        static unsigned hardware_concurrency();

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

        void interrupt();
        bool interruption_requested() const;

        // backwards compatibility
        bool operator==(const thread& other) const;
        bool operator!=(const thread& other) const;

        static void yield();
        static void sleep(const system_time& xt);
    };

    void swap(thread& lhs,thread& rhs);
    detail::thread_move_t<thread> move(detail::thread_move_t<thread> t);

[section:default_constructor Default Constructor]

    thread();

[variablelist

[[Effects:] [Constructs a __thread__ instance that refers to __not_a_thread__.]]

[[Throws:] [Nothing]]

]

[endsect]

[section:move_constructor Move Constructor]

    thread(detail::thread_move_t<thread> other);

[variablelist

[[Effects:] [Transfers ownership of the thread managed by `other` (if any) to the newly constructed __thread__ instance.]]

[[Postconditions:] [`other->get_id()==thread::id()`]]

[[Throws:] [Nothing]]

]

[endsect]

[section:move_assignment Move assignment operator]

    thread& operator=(detail::thread_move_t<thread> other);

[variablelist

[[Effects:] [Transfers ownership of the thread managed by `other` (if
any) to `*this`. If there was a thread previously associated with
`*this` then that thread is detached.]]

[[Postconditions:] [`other->get_id()==thread::id()`]]

[[Throws:] [Nothing]]

]

[endsect]

[section:callable_constructor Thread Constructor]

    template<typename Callable>
    thread(Callable func);

[variablelist

[[Preconditions:] [`Callable` must by 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. If this invocation results in an exception being propagated into the internals of the thread library that is
not of type __thread_interrupted__, then `std::terminate()` will be called.]]

[[Postconditions:] [`*this` refers to the newly created thread of execution.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]

[endsect]

[section:multiple_argument_constructor Thread Constructor with arguments]

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

[variablelist

[[Preconditions:] [`F` and each `A`n must by copyable or movable.]]

[[Effects:] [As if [link
thread.thread_management.thread.callable_constructor
`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:] [__thread_resource_error__ if an error occurs.]]

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

]

[endsect]

[section:destructor Thread Destructor]

    ~thread();

[variablelist

[[Effects:] [If `*this` has an associated thread of execution, calls __detach__. Destroys `*this`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:joinable Member function `joinable()`]

    bool joinable() const;

[variablelist

[[Returns:] [`true` if `*this` refers to a thread of execution, `false` otherwise.]]

[[Throws:] [Nothing]]

]


[endsect]

[section:join Member function `join()`]

    void join();

[variablelist

[[Preconditions:] [`this->get_id()!=boost::this_thread::get_id()`]]

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

[[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:] [__thread_interrupted__ if the current thread of execution is interrupted.]]

[[Notes:] [`join()` is one of the predefined __interruption_points__.]]

]

[endsect]

[section:timed_join Member function `timed_join()`]

    bool timed_join(const system_time& wait_until);

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

[variablelist

[[Preconditions:] [`this->get_id()!=boost::this_thread::get_id()`]]

[[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:] [__thread_interrupted__ if the current thread of execution is interrupted.]]

[[Notes:] [`timed_join()` is one of the predefined __interruption_points__.]]

]

[endsect]

[section:detach Member function `detach()`]

    void detach();

[variablelist

[[Effects:] [If `*this` refers to a thread of execution, that thread of execution becomes detached, and no longer has an associated __thread__ object.]]

[[Postconditions:] [`*this` no longer refers to any thread of execution.]]

[[Throws:] [Nothing]]

]

[endsect]


[section:get_id Member function `get_id()`]

    thread::id get_id() const;

[variablelist

[[Returns:] [If `*this` refers to a thread of execution, an instance of __thread_id__ that represents that thread. Otherwise returns
a default-constructed __thread_id__.]]

[[Throws:] [Nothing]]

]

[endsect]

[section:interrupt Member function `interrupt()`]

    void interrupt();

[variablelist

[[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]]

]
        

[endsect]

[section:hardware_concurrency Static member function `hardware_concurrency()`]

    unsigned hardware_concurrency();

[variablelist

[[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]]

]

[endsect]

[section:nativehandle Member function `native_handle()`]

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

[variablelist

[[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.]]

]

[endsect]

[section:equals `operator==`]

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

[variablelist

[[Returns:] [`get_id()==other.get_id()`]]

]

[endsect]

[section:not_equals `operator!=`]

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

[variablelist

[[Returns:] [`get_id()!=other.get_id()`]]

]

[endsect]

[section:sleep Static member function `sleep()`]

    void sleep(system_time const& abs_time);

[variablelist

[[Effects:] [Suspends the current thread until the specified time has been reached.]]

[[Throws:] [__thread_interrupted__ if the current thread of execution is interrupted.]]

[[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]

]

[endsect]

[section:yield Static member function `yield()`]

    void yield();

[variablelist

[[Effects:] [See [link thread.thread_management.this_thread.yield `boost::this_thread::yield()`].]]

]

[endsect]

[section:swap Member function `swap()`]

    void swap(thread& other);

[variablelist

[[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.]]

]

[endsect]

[section:non_member_swap Non-member function `swap()`]

    #include <boost/thread/thread.hpp>

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

[variablelist

[[Effects:] [[link thread.thread_management.thread.swap `lhs.swap(rhs)`].]]

]

[endsect]

[section:non_member_move Non-member function `move()`]

    #include <boost/thread/thread.hpp>

    detail::thread_move_t<thread> move(detail::thread_move_t<thread> t)

[variablelist

[[Returns:] [`t`.]]

]

Enables moving thread objects. e.g.

    extern void some_func();
    boost::thread t(some_func);
    boost::thread t2(boost::move(t)); // transfer thread from t to t2

[endsect]


[section:id Class `boost::thread::id`]

    #include <boost/thread/thread.hpp>

    class thread::id
    {
    public:
        id();

        bool operator==(const id& y) const;
        bool operator!=(const id& y) const;
        bool operator<(const id& y) const;
        bool operator>(const id& y) const;
        bool operator<=(const id& y) const;
        bool operator>=(const id& y) const;

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

[section:constructor Default constructor]

    id();

[variablelist

[[Effects:] [Constructs a __thread_id__ instance that represents __not_a_thread__.]]

[[Throws:] [Nothing]]

]

[endsect]

[section:is_equal `operator==`]

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

[variablelist

[[Returns:] [`true` if `*this` and `y` both represent the same thread of execution, or both represent __not_a_thread__, `false`
otherwise.]]

[[Throws:] [Nothing]]

]

[endsect]

[section:not_equal `operator!=`]

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

[variablelist

[[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]]

]

[endsect]

[section:less_than `operator<`]

    bool operator<(const id& y) const;

[variablelist

[[Returns:] [`true` if `*this!=y` is `true` and the implementation-defined total order of __thread_id__ values places `*this` before
`y`, `false` otherwise.]]

[[Throws:] [Nothing]]

[[Note:] [A __thread_id__ instance representing __not_a_thread__ will always compare less than an instance representing a thread of
execution.]]

]

[endsect]


[section:greater_than `operator>`]

    bool operator>(const id& y) const;

[variablelist

[[Returns:] [`y<*this`]]

[[Throws:] [Nothing]]

]

[endsect]

[section:less_than_or_equal `operator<=`]

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

[variablelist

[[Returns:] [`!(y<*this)`]]

[[Throws:] [Nothing]]

]

[endsect]

[section:greater_than_or_equal `operator>=`]

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

[variablelist

[[Returns:] [`!(*this<y)`]]

[[Throws:] [Nothing]]

]

[endsect]

[section:stream_out Friend `operator<<`]

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

[variablelist

[[Effects:] [Writes a representation of the __thread_id__ instance `x` to the stream `os`, such that the representation of two
instances of __thread_id__ `a` and `b` is the same if `a==b`, and different if `a!=b`.]]

[[Returns:] [`os`]]

]

[endsect]


[endsect]

[endsect]

[section:this_thread Namespace `this_thread`]

[section:get_id Non-member function `get_id()`]

    #include <boost/thread/thread.hpp>

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

[variablelist

[[Returns:] [An instance of __thread_id__ that represents that currently executing thread.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]

[endsect]

[section:interruption_point Non-member function `interruption_point()`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        void interruption_point();
    }

[variablelist

[[Effects:] [Check to see if the current thread has been interrupted.]]

[[Throws:] [__thread_interrupted__ if __interruption_enabled__ and __interruption_requested__ both return `true`.]]

]

[endsect]

[section:interruption_requested Non-member function `interruption_requested()`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        bool interruption_requested();
    }

[variablelist

[[Returns:] [`true` if interruption has been requested for the current thread, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:interruption_enabled Non-member function `interruption_enabled()`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        bool interruption_enabled();
    }

[variablelist

[[Returns:] [`true` if interruption has been enabled for the current thread, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:sleep Non-member function `sleep()`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        template<typename TimeDuration>
        void sleep(TimeDuration const& rel_time);
        void sleep(system_time const& abs_time)
    }

[variablelist

[[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:] [__thread_interrupted__ if the current thread of execution is interrupted.]]

[[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]

]

[endsect]

[section:yield Non-member function `yield()`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        void yield();
    }

[variablelist

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

[[Throws:] [Nothing.]]

]

[endsect]

[section:disable_interruption Class `disable_interruption`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        class disable_interruption
        {
        public:
            disable_interruption();
            ~disable_interruption();
        };
    }

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

[section:constructor Constructor]

    disable_interruption();

[variablelist

[[Effects:] [Stores the current state of __interruption_enabled__ and disables interruption for the current thread.]]

[[Postconditions:] [__interruption_enabled__ returns `false` for the current thread.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:destructor Destructor]

    ~disable_interruption();

[variablelist

[[Preconditions:] [Must be called from the same thread from which `*this` was constructed.]]

[[Effects:] [Restores the current state of __interruption_enabled__ for the current thread to that prior to the construction of `*this`.]]

[[Postconditions:] [__interruption_enabled__ for the current thread returns the value stored in the constructor of `*this`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[endsect]

[section:restore_interruption Class `restore_interruption`]

    #include <boost/thread/thread.hpp>

    namespace this_thread
    {
        class restore_interruption
        {
        public:
            explicit restore_interruption(disable_interruption& disabler);
            ~restore_interruption();
        };
    }

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 __disable_interruption__. When the instance
is destroyed, interruption is again disabled. Instances of `restore_interruption` cannot be copied or moved.

[section:constructor Constructor]

    explicit restore_interruption(disable_interruption& disabler);

[variablelist

[[Preconditions:] [Must be called from the same thread from which `disabler` was constructed.]]

[[Effects:] [Restores the current state of __interruption_enabled__ for the current thread to that prior to the construction of `disabler`.]]

[[Postconditions:] [__interruption_enabled__ for the current thread returns the value stored in the constructor of `disabler`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:destructor Destructor]

    ~restore_interruption();

[variablelist

[[Preconditions:] [Must be called from the same thread from which `*this` was constructed.]]

[[Effects:] [Disables interruption for the current thread.]]

[[Postconditions:] [__interruption_enabled__ for the current thread returns `false`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[endsect]

[section:atthreadexit Non-member function template `at_thread_exit()`]

    #include <boost/thread/thread.hpp>

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

[variablelist

[[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, __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()`]]

]

[endsect]

[endsect]

[section:threadgroup Class `thread_group`]

    #include <boost/thread/thread.hpp>

    class thread_group:
        private noncopyable
    {
    public:
        thread_group();
        ~thread_group();

        template<typename F>
        thread* create_thread(F threadfunc);
        void add_thread(thread* thrd);
        void remove_thread(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.

[section:constructor Constructor]

    thread_group();

[variablelist

[[Effects:] [Create a new thread group with no threads.]]

]

[endsect]

[section:destructor Destructor]

    ~thread_group();

[variablelist

[[Effects:] [Destroy `*this` and `delete` all __thread__ objects in the group.]]

]

[endsect]

[section:create_thread Member function `create_thread()`]

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

[variablelist

[[Effects:] [Create a new __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 __thread__ object.]]

]

[endsect]

[section:add_thread Member function `add_thread()`]

    void add_thread(thread* thrd);

[variablelist

[[Precondition:] [The expression `delete thrd` is well-formed and will not result in undefined behaviour.]]

[[Effects:] [Take ownership of the __thread__ object pointed to by `thrd` and add it to the group.]]

[[Postcondition:] [`this->size()` is increased by one.]]

]

[endsect]

[section:remove_thread Member function `remove_thread()`]

    void remove_thread(thread* thrd);

[variablelist

[[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.]]

]

[endsect]

[section:join_all Member function `join_all()`]

    void join_all();

[variablelist

[[Effects:] [Call `join()` on each __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.]]

]

[endsect]

[section:interrupt_all Member function `interrupt_all()`]

    void interrupt_all();

[variablelist

[[Effects:] [Call `interrupt()` on each __thread__ object in the group.]]

]

[endsect]

[section:size Member function `size()`]

    int size();

[variablelist

[[Returns:] [The number of threads in the group.]]

[[Throws:] [Nothing.]]

]

[endsect]


[endsect]

[endsect]