boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Scoped Threads</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="thread_management.html" title="Thread Management"> <link rel="next" href="synchronization.html" title="Synchronization"> </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="thread_management.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="synchronization.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.ScopedThreads"></a><a class="link" href="ScopedThreads.html" title="Scoped Threads">Scoped Threads</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="ScopedThreads.html#thread.ScopedThreads.motovation">Motivation</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.tutorial">Tutorial</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.thread_functors">Free Thread Functors</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread">Class <code class="computeroutput">strict_scoped_thread</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread">Class <code class="computeroutput">scoped_thread</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.non_member_swap">Non-member function <code class="computeroutput">swap(scoped_thread&,scoped_thread&)</code></a></dt> </dl></div> <h4> <a name="thread.ScopedThreads.h0"></a> <a name="thread.ScopedThreads.synopsis"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.synopsis">Synopsis</a> </h4> <pre class="programlisting">//#include <boost/thread/scoped_thread.hpp> struct detach; struct join_if_joinable; struct interrupt_and_join_if_joinable; template <class CallableThread = join_if_joinable> class strict_scoped_thread; template <class CallableThread = join_if_joinable> class scoped_thread; void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept; </pre> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.ScopedThreads.motovation"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.motovation" title="Motivation">Motivation</a> </h3></div></div></div> Based on the scoped_thread class defined in C++ Concurrency in Action Boost.Thread defines a thread wrapper class that instead of calling terminate if the thread is joinable on destruction, call a specific action given as template parameter. While the scoped_thread class defined in C++ Concurrency in Action is closer to strict_scoped_thread class that doesn't allows any change in the wrapped thread, Boost.Thread provides a class scoped_thread that provides the same non-deprecated interface than <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a>. </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.ScopedThreads.tutorial"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.tutorial" title="Tutorial">Tutorial</a> </h3></div></div></div> Scoped Threads are wrappers around a thread that allows the user to state what to do at destruction time. One of the common uses is to join the thread at destruction time so this is the default behavior. This is the single difference respect to a thread. While thread call std::terminate() on the destructor is the thread is joinable, strict_scoped_thread<> or scoped_thread<> join the thread if joinable. The difference between strict_scoped_thread and scoped_thread is that the strict_scoped_thread hides completely the owned thread and so the user can do nothing with the owned thread other than the specific action given as parameter, while scoped_thread provide the same interface than <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> and forwards all the operations. <pre class="programlisting">boost::strict_scoped_thread<> t1((boost::thread(f))); //t1.detach(); // compile fails boost::scoped_thread<> t2((boost::thread(f))); t2.detach(); </pre> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.ScopedThreads.thread_functors"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.thread_functors" title="Free Thread Functors">Free Thread Functors</a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="ScopedThreads.html#thread.ScopedThreads.thread_functors.detach">Functor <code class="computeroutput">detach</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.thread_functors.join_if_joinable">Functor <code class="computeroutput">join_if_joinable</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.thread_functors.interrupt_and_join_if_joinable">Functor <code class="computeroutput">interrupt_and_join_if_joinable</code></a></dt> </dl></div> <pre class="programlisting">//#include <boost/thread/scoped_thread.hpp> struct detach; struct join_if_joinable; struct interrupt_and_join_if_joinable; </pre> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.thread_functors.detach"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.thread_functors.detach" title="Functor detach">Functor <code class="computeroutput">detach</code></a> </h4></div></div></div> <pre class="programlisting">struct detach { void operator()(thread& t) { t.detach(); } }; </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.thread_functors.join_if_joinable"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.thread_functors.join_if_joinable" title="Functor join_if_joinable">Functor <code class="computeroutput">join_if_joinable</code></a> </h4></div></div></div> <pre class="programlisting">struct join_if_joinable { void operator()(thread& t) { if (t.joinable()) { t.join(); } } }; </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.thread_functors.interrupt_and_join_if_joinable"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.thread_functors.interrupt_and_join_if_joinable" title="Functor interrupt_and_join_if_joinable">Functor <code class="computeroutput">interrupt_and_join_if_joinable</code></a> </h4></div></div></div> <pre class="programlisting">struct interrupt_and_join_if_joinable { void operator()(thread& t) { t.interrupt(); if (t.joinable()) { t.join(); } } }; </pre> </div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.ScopedThreads.strict_scoped_thread"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread" title="Class strict_scoped_thread">Class <code class="computeroutput">strict_scoped_thread</code></a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.default_constructor">Constructor from a <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.call_constructor">Move Constructor from a Callable</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.destructor">Destructor</a></dt> </dl></div> <pre class="programlisting">// #include <boost/thread/scoped_thread.hpp> template <class CallableThread = join_if_joinable> class strict_scoped_thread { thread t_; // for exposition purposes only public: strict_scoped_thread(strict_scoped_thread const&) = delete; strict_scoped_thread& operator=(strict_scoped_thread const&) = delete; explicit strict_scoped_thread(thread&& t) noexcept; template <typename F&&, typename ...Args> explicit strict_scoped_thread(F&&, Args&&...); ~strict_scoped_thread(); }; </pre> RAI <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> wrapper adding a specific destroyer allowing to master what can be done at destruction time. CallableThread: A callable <code class="computeroutput">void(thread&)</code>. The default is a <code class="computeroutput">join_if_joinable</code>. <code class="computeroutput">std/boost::thread</code> destructor terminates the program if the <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> is not joinable. This wrapper can be used to join the thread before destroying it seems a natural need. <h5> <a name="thread.ScopedThreads.strict_scoped_thread.h0"></a> <a name="thread.ScopedThreads.strict_scoped_thread.example"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.example">Example</a> </h5> <pre class="programlisting">boost::strict_scoped_thread<> t((boost::thread(F))); </pre> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.strict_scoped_thread.default_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.default_constructor" title="Constructor from a thread">Constructor from a <code class="computeroutput">thread</code></a> </h4></div></div></div> <pre class="programlisting">explicit strict_scoped_thread(thread&& t) noexcept; </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> move the thread to own <code class="computeroutput">t_</code> </dd> <dt>Throws:</dt> <dd> Nothing </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.strict_scoped_thread.call_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.call_constructor" title="Move Constructor from a Callable">Move Constructor from a Callable</a> </h4></div></div></div> <pre class="programlisting">template <typename F&&, typename ...Args> explicit strict_scoped_thread(F&&, Args&&...); </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Construct a internal thread in place. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">*this.t_</code> refers to the newly created thread of execution and <code class="computeroutput">this->get_id()!=thread::id()</code>. </dd> <dt>Throws:</dt> <dd> Any exception the thread construction can throw. </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.strict_scoped_thread.destructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.strict_scoped_thread.destructor" title="Destructor">Destructor</a> </h4></div></div></div> <pre class="programlisting">~strict_scoped_thread(); </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Equivalent to <code class="computeroutput">CallableThread()(t_)</code>. </dd> <dt>Throws:</dt> <dd> Nothing: The <code class="computeroutput">CallableThread()(t_)</code> should not throw when joining the thread as the scoped variable is on a scope outside the thread function. </dd> </dl> </div> </div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="thread.ScopedThreads.scoped_thread"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread" title="Class scoped_thread">Class <code class="computeroutput">scoped_thread</code></a> </h3></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.default_constructor">Default Constructor</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.move_constructor">Move Constructor</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.move_assignment">Move assignment operator</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.thread_constructor">Move Constructor from a <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.call_constructor">Move Constructor from a Callable</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.destructor">Destructor</a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.joinable">Member function <code class="computeroutput">joinable()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.join">Member function <code class="computeroutput">join()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.try_join_for">Member function <code class="computeroutput">try_join_for()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.try_join_until">Member function <code class="computeroutput">try_join_until()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.detach">Member function <code class="computeroutput">detach()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.get_id">Member function <code class="computeroutput">get_id()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.interrupt">Member function <code class="computeroutput">interrupt()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.hardware_concurrency">Static member function <code class="computeroutput">hardware_concurrency()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.physical_concurrency">Static member function <code class="computeroutput">physical_concurrency()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.nativehandle">Member function <code class="computeroutput">native_handle()</code></a></dt> <dt><a href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.swap">Member function <code class="computeroutput">swap()</code></a></dt> </dl></div> <pre class="programlisting">#include <boost/thread/scoped_thread.hpp> template <class CallableThread> class scoped_thread { thread t_; // for exposition purposes only public: scoped_thread() noexcept; scoped_thread(const scoped_thread&) = delete; scoped_thread& operator=(const scoped_thread&) = delete; explicit scoped_thread(thread&& th) noexcept; template <typename F&&, typename ...Args> explicit scoped_thread(F&&, Args&&...); ~scoped_thread(); // move support scoped_thread(scoped_thread && x) noexcept; scoped_thread& operator=(scoped_thread && x) noexcept; void swap(scoped_thread& x) noexcept; typedef thread::id id; id get_id() const noexcept; bool joinable() const noexcept; void join(); #ifdef BOOST_THREAD_USES_CHRONO template <class Rep, class Period> bool try_join_for(const chrono::duration<Rep, Period>& rel_time); template <class Clock, class Duration> bool try_join_until(const chrono::time_point<Clock, Duration>& t); #endif void detach(); static unsigned hardware_concurrency() noexcept; static unsigned physical_concurrency() noexcept; typedef thread::native_handle_type native_handle_type; native_handle_type native_handle(); #if defined BOOST_THREAD_PROVIDES_INTERRUPTIONS void interrupt(); bool interruption_requested() const noexcept; #endif }; void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept; </pre> RAI <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> wrapper adding a specific destroyer allowing to master what can be done at destruction time. CallableThread: A callable void(thread&). The default is join_if_joinable. thread std::thread destructor terminates the program if the thread is not joinable. Having a wrapper that can join the thread before destroying it seems a natural need. Remark: <code class="computeroutput">scoped_thread</code> is not a <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> as <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> is not designed to be derived from as a polymorphic type. Anyway <code class="computeroutput">scoped_thread</code> can be used in most of the contexts a <a class="link" href="thread_management.html#thread.thread_management.thread" title="Class thread"><code class="computeroutput">thread</code></a> could be used as it has the same non-deprecated interface with the exception of the construction. <h5> <a name="thread.ScopedThreads.scoped_thread.h0"></a> <a name="thread.ScopedThreads.scoped_thread.example"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.example">Example</a> </h5> <pre class="programlisting">boost::scoped_thread<> t((boost::thread(F))); t.interrupt(); </pre> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.default_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.default_constructor" title="Default Constructor">Default Constructor</a> </h4></div></div></div> <pre class="programlisting">scoped_thread() noexcept; </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Constructs a scoped_thread instance that wraps to Not-a-Thread. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">this->get_id()==thread::id()</code> </dd> <dt>Throws:</dt> <dd> Nothing </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.move_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.move_constructor" title="Move Constructor">Move Constructor</a> </h4></div></div></div> <pre class="programlisting">scoped_thread(scoped_thread&& other) noexcept; </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Transfers ownership of the scoped_thread managed by <code class="computeroutput">other</code> (if any) to the newly constructed scoped_thread instance. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">other.get_id()==thread::id()</code> and <code class="computeroutput">get_id()</code> returns the value of <code class="computeroutput">other.get_id()</code> prior to the construction </dd> <dt>Throws:</dt> <dd> Nothing </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.move_assignment"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.move_assignment" title="Move assignment operator">Move assignment operator</a> </h4></div></div></div> <pre class="programlisting">scoped_thread& operator=(scoped_thread&& other) noexcept; </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Transfers ownership of the scoped_thread managed by <code class="computeroutput">other</code> (if any) to <code class="computeroutput">*this</code>. - if defined <code class="computeroutput">BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE</code>: If there was a <code class="computeroutput">scoped_thread</code> previously associated with <code class="computeroutput">*this</code> then that <code class="computeroutput">scoped_thread</code> is detached, DEPRECATED - if defined <code class="computeroutput">BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE</code>: If the <code class="computeroutput">scoped_thread</code> is joinable calls to std::terminate. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">other->get_id()==thread::id()</code> and <code class="computeroutput">get_id()</code> returns the value of <code class="computeroutput">other.get_id()</code> prior to the assignment. </dd> <dt>Throws:</dt> <dd> Nothing </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.thread_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.thread_constructor" title="Move Constructor from a thread">Move Constructor from a <code class="computeroutput">thread</code></a> </h4></div></div></div> <pre class="programlisting">scoped_thread(thread&& t); </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> move the thread to own <code class="computeroutput">t_</code>. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">*this.t_</code> refers to the newly created thread of execution and <code class="computeroutput">this->get_id()!=thread::id()</code>. </dd> <dt>Throws:</dt> <dd> Nothing </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.call_constructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.call_constructor" title="Move Constructor from a Callable">Move Constructor from a Callable</a> </h4></div></div></div> <pre class="programlisting">template <typename F&&, typename ...Args> explicit scoped_thread(F&&, Args&&...); </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Construct a internal thread in place. </dd> <dt>Postconditions:</dt> <dd> <code class="computeroutput">*this.t_</code> refers to the newly created thread of execution and <code class="computeroutput">this->get_id()!=thread::id()</code>. </dd> <dt>Throws:</dt> <dd> Any exception the thread construction can throw. </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.destructor"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.destructor" title="Destructor">Destructor</a> </h4></div></div></div> <pre class="programlisting">~scoped_thread(); </pre> <div class="variablelist"> <dl class="variablelist"> <dt>Effects:</dt> <dd> Equivalent to <code class="computeroutput">CallableThread()(t_)</code>. </dd> <dt>Throws:</dt> <dd> Nothing: The <code class="computeroutput">CallableThread()(t_)</code> should not throw when joining the thread as the scoped variable is on a scope outside the thread function. </dd> </dl> </div> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="thread.ScopedThreads.scoped_thread.joinable"></a><a class="link" href="ScopedThreads.html#thread.ScopedThreads.scoped_thread.joinable" title="Member function joinable()">Member function <code class="computeroutput">join