boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Thread Management</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../thread.html" title="Chapter 30. Thread 4.4.0"> <link rel="prev" href="future.html" title="Future"> <link rel="next" href="ScopedThreads.html" title="Scoped Threads"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="future.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="ScopedThreads.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="thread.thread_management"></a><a class="link" href="thread_management.html" title="Thread Management">Thread Management</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="thread_management.html#thread.thread_management.synopsis">Synopsis</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial">Tutorial</a></dt> <dt><a href="thread_management.html#thread.thread_management.thread">Class <code class="computeroutput">thread</code></a></dt> <dt><a href="thread_management.html#thread.thread_management.this_thread">Namespace <code class="computeroutput">this_thread</code></a></dt> <dt><a href="thread_management.html#thread.thread_management.threadgroup">Class <code class="computeroutput">thread_group</code> EXTENSION</a></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.thread_management.synopsis"></a><a class="link" href="thread_management.html#thread.thread_management.synopsis" title="Synopsis">Synopsis</a> </h3></div></div></div> <pre class="programlisting">#include <boost/thread/thread.hpp> namespace boost { class thread; void swap(thread& lhs,thread& rhs) noexcept; namespace this_thread { thread::id get_id() noexcept; template<typename TimeDuration> void yield() noexcept; // DEPRECATED template <class Clock, class Duration> void sleep_until(const chrono::time_point<Clock, Duration>& abs_time); template <class Rep, class Period> void sleep_for(const chrono::duration<Rep, Period>& rel_time); 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 } </pre> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.thread_management.tutorial"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial" title="Tutorial">Tutorial</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="thread_management.html#thread.thread_management.tutorial.launching">Launching threads</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.attributes">Thread attributes</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.exceptions">Exceptions in thread functions</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.detach">Detaching thread</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.join">Joining a thread</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.destructor1">Destructor V1</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.destructor2">Destructor V2</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.interruption">Interruption</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.id">Thread IDs</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.native_in">Using native interfaces with Boost.Thread resources</a></dt> <dt><a href="thread_management.html#thread.thread_management.tutorial.native_from">Using Boost.Thread interfaces in a native thread</a></dt> </dl></div> The <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> class is responsible for launching and managing threads. Each <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object represents a single thread of execution, or Not-a-Thread, and at most one <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object represents a given thread of execution: objects of type <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> are not copyable. Objects of type <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> 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. <pre class="programlisting">boost::thread make_thread(); void f() { boost::thread some_thread=make_thread(); some_thread.join(); } </pre> <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> On compilers that support rvalue references, <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> provides a proper move constructor and move-assignment operator, and therefore meets the C++0x MoveConstructible and MoveAssignable concepts. With such compilers, <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> 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. </td></tr> </table></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.launching"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.launching" title="Launching threads">Launching threads</a> </h4></div></div></div> 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 <code class="computeroutput">boost::ref</code> 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. <pre class="programlisting">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 </pre> If you wish to construct an instance of <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> with a function or callable object that requires arguments to be supplied, this can be done by passing additional arguments to the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> constructor: <pre class="programlisting">void find_the_question(int the_answer); boost::thread deep_thought_2(find_the_question,42); </pre> The arguments are copied into the internal thread structure: if a reference is required, use <code class="computeroutput">boost::ref</code>, just as for references to callable functions. There is an unspecified limit on the number of additional arguments that can be passed. </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.attributes"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.attributes" title="Thread attributes">Thread attributes</a> </h4></div></div></div> 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: <pre class="programlisting">boost::thread::attributes attrs; attrs.set_size(4096*10); boost::thread deep_thought_2(attrs, find_the_question, 42); </pre> 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. <pre class="programlisting">boost::thread::attributes attrs; // set portable attributes // ... attr.set_stack_size(4096*10); #if defined(BOOST_THREAD_PLATFORM_WIN32) // ... window version #elif defined(BOOST_THREAD_PLATFORM_PTHREAD) // ... pthread version pthread_attr_setschedpolicy(attr.get_native_handle(), SCHED_RR); #else #error "Boost threads unavailable on this platform" #endif boost::thread th(attrs, find_the_question, 42); </pre> 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 <pre class="programlisting">#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 </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.exceptions"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.exceptions" title="Exceptions in thread functions">Exceptions in thread functions</a> </h4></div></div></div> If the function or callable object passed to the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> constructor propagates an exception when invoked that is not of type <code class="computeroutput">boost::thread_interrupted</code>, <code class="computeroutput">std::terminate()</code> is called. </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.detach"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.detach" title="Detaching thread">Detaching thread</a> </h4></div></div></div> A thread can be detached by explicitly invoking the <a class="link" href="thread_management.html#thread.thread_management.thread.detach" title="Member function detach()"><code class="computeroutput">detach()</code></a> member function on the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object. In this case, the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object ceases to represent the now-detached thread, and instead represents Not-a-Thread. <pre class="programlisting">int main() { boost::thread t(my_func); t.detach(); } </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.join"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.join" title="Joining a thread">Joining a thread</a> </h4></div></div></div> In order to wait for a thread of execution to finish, the <a class="link" href="thread_management.html#thread.thread_management.thread.join" title="Member function join()"><code class="computeroutput">join()</code></a>, __join_for or __join_until ( <a class="link" href="thread_management.html#thread.thread_management.thread.timed_join" title="Member function timed_join() DEPRECATED"><code class="computeroutput">timed_join()</code></a> deprecated) member functions of the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object must be used. <a class="link" href="thread_management.html#thread.thread_management.thread.join" title="Member function join()"><code class="computeroutput">join()</code></a> will block the calling thread until the thread represented by the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object has completed. <pre class="programlisting">int main() { boost::thread t(my_func); t.join(); } </pre> If the thread of execution represented by the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object has already completed, or the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object represents Not-a-Thread, then <a class="link" href="thread_management.html#thread.thread_management.thread.join" title="Member function join()"><code class="computeroutput">join()</code></a> returns immediately. <pre class="programlisting">int main() { boost::thread t; t.join(); // do nothing } </pre> 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. <pre class="programlisting">int main() { boost::thread t; if ( t.join_for(boost::chrono::milliseconds(500)) ) // do something else t.join(); // join anyway } </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.destructor1"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.destructor1" title="Destructor V1">Destructor V1</a> </h4></div></div></div> When the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> 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 <a class="link" href="thread_management.html#thread.thread_management.thread.detach" title="Member function detach()"><code class="computeroutput">detach()</code></a> member function on the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object. In this case, the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object ceases to represent the now-detached thread, and instead represents Not-a-Thread. </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.destructor2"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.destructor2" title="Destructor V2">Destructor V2</a> </h4></div></div></div> When the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object that represents a thread of execution is destroyed the program terminates if the thread is __joinable__. <pre class="programlisting">int main() { boost::thread t(my_func); } // calls std::terminate() </pre> You can use a thread_joiner to ensure that the thread has been joined at the thread destructor. <pre class="programlisting">int main() { boost::thread t(my_func); boost::thread_joiner g(t); // do someting else } // here the thread_joiner destructor will join the thread before it is destroyed. </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.thread_management.tutorial.interruption"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.interruption" title="Interruption">Interruption</a> </h4></div></div></div> A running thread can be interrupted by invoking the <a class="link" href="thread_management.html#thread.thread_management.thread.interrupt" title="Member function interrupt() EXTENSION"><code class="computeroutput">interrupt()</code></a> member function of the corresponding <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">boost::thread</code></a> object. When the interrupted thread next executes one of the specified <a class="link" href="thread_management.html#interruption_points">interruption points</a> (or if it is currently blocked whilst executing one) with interruption enabled, then a <code class="computeroutput">boost::thread_interrupted</code> 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 <a class="link" href="thread_management.html#thread.thread_management.this_thread.disable_interruption" title="Class disable_interruption EXTENSION"><code class="computeroutput">boost::this_thread::disable_interruption</code></a>. 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: <pre class="programlisting">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 } </pre> The effects of an instance of <a class="link" href="thread_management.html#thread.thread_management.this_thread.disable_interruption" title="Class disable_interruption EXTENSION"><code class="computeroutput">boost::this_thread::disable_interruption</code></a> can be temporarily reversed by constructing an instance of <a class="link" href="thread_management.html#thread.thread_management.this_thread.restore_interruption" title="Class restore_interruption EXTENSION"><code class="computeroutput">boost::this_thread::restore_interruption</code></a>, passing in the <a class="link" href="thread_management.html#thread.thread_management.this_thread.disable_interruption" title="Class disable_interruption EXTENSION"><code class="computeroutput">boost::this_thread::disable_interruption</code></a> object in question. This will restore the interruption state to what it was when the <a class="link" href="thread_management.html#thread.thread_management.this_thread.disable_interruption" title="Class disable_interruption EXTENSION"><code class="computeroutput">boost::this_thread::disable_interruption</code></a> object was constructed, and then disable interruption again when the <a class="link" href="thread_management.html#thread.thread_management.this_thread.restore_interruption" title="Class restore_interruption EXTENSION"><code class="computeroutput">boost::this_thread::restore_interruption</code></a> object is destroyed. <pre class="programlisting">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 } </pre> At any point, the interruption state for the current thread can be queried by calling <a class="link" href="thread_management.html#thread.thread_management.this_thread.interruption_enabled" title="Non-member function interruption_enabled() EXTENSION"><code class="computeroutput">boost::this_thread::interruption_enabled()</code></a>. <a name="interruption_points"></a><h6> <a name="thread.thread_management.tutorial.interruption.h0"></a> <a name="thread.thread_management.tutorial.interruption.predefined_interruption_points"></a><a class="link" href="thread_management.html#thread.thread_management.tutorial.interruption.predefined_interruption_points">Predefined Interruption Points</a> </h6> The following functions are interruption points, which will throw <code class="computeroutput">boost::thread_interrupted</code> if interruption is enabled for the current thread, and interruption is requested for the current thread: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> <a class="link" href="thread_management.html#thread.thread_management.thread.join" title="Member function join()"><code class="computeroutput">boost<s