<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.4"/>
<title>c++-gtk-utils: Cgu::Thread::Thread Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">c++-gtk-utils
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.4 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="classes.html"><span>Class Index</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespaceCgu.html">Cgu</a></li><li class="navelem"><a class="el" href="namespaceCgu_1_1Thread.html">Thread</a></li><li class="navelem"><a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> |
<a href="#pub-static-methods">Static Public Member Functions</a> |
<a href="classCgu_1_1Thread_1_1Thread-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">Cgu::Thread::Thread Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>A class representing a pthread thread.
<a href="classCgu_1_1Thread_1_1Thread.html#details">More...</a></p>
<p><code>#include <<a class="el" href="thread_8h_source.html">c++-gtk-utils/thread.h</a>></code></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a9d93cd72283ba3103e1695962b3840e4"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#a9d93cd72283ba3103e1695962b3840e4">Thread</a> (const <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a> &)=delete</td></tr>
<tr class="separator:a9d93cd72283ba3103e1695962b3840e4"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ae12db47abdf8ab9c5e1e9bb8ca02b036"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a> & </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae12db47abdf8ab9c5e1e9bb8ca02b036">operator=</a> (const <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a> &)=delete</td></tr>
<tr class="separator:ae12db47abdf8ab9c5e1e9bb8ca02b036"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a3d939f57b95a6d947c0cd339b102a189"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#a3d939f57b95a6d947c0cd339b102a189">cancel</a> () noexcept</td></tr>
<tr class="separator:a3d939f57b95a6d947c0cd339b102a189"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a91c7dc81bd997444d77185d5a5cd2fc9"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join</a> () noexcept</td></tr>
<tr class="separator:a91c7dc81bd997444d77185d5a5cd2fc9"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ae54e2ca2531928b4debbff0019ec9695"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach</a> () noexcept</td></tr>
<tr class="separator:ae54e2ca2531928b4debbff0019ec9695"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a895a471861aaaad5d20ea26a256c98d1"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#a895a471861aaaad5d20ea26a256c98d1">is_caller</a> () noexcept</td></tr>
<tr class="separator:a895a471861aaaad5d20ea26a256c98d1"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-static-methods"></a>
Static Public Member Functions</h2></td></tr>
<tr class="memitem:a0c8a852f0739170f6a5ed8657031774c"><td class="memItemLeft" align="right" valign="top">static std::unique_ptr<br class="typebreak"/>
< <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Cgu::Thread::Thread</a> > </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#a0c8a852f0739170f6a5ed8657031774c">start</a> (const <a class="el" href="namespaceCgu_1_1Callback.html#ab0fdf0ebb22f2a7cc813657f6d90a94d">Cgu::Callback::Callback</a> *cb, bool joinable)</td></tr>
<tr class="separator:a0c8a852f0739170f6a5ed8657031774c"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:aa7ffae4b51c245cc98bf1e029c6a900c"><td class="memTemplParams" colspan="2">template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Cgu::Callback::Callback*>::value>::type> </td></tr>
<tr class="memitem:aa7ffae4b51c245cc98bf1e029c6a900c"><td class="memTemplItemLeft" align="right" valign="top">static std::unique_ptr<br class="typebreak"/>
< <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Cgu::Thread::Thread</a> > </td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1Thread.html#aa7ffae4b51c245cc98bf1e029c6a900c">start</a> (F &&func, bool joinable)</td></tr>
<tr class="separator:aa7ffae4b51c245cc98bf1e029c6a900c"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>A class representing a pthread thread. </p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classCgu_1_1Thread_1_1Mutex.html" title="A wrapper class for pthread mutexes. ">Thread::Mutex</a> <a class="el" href="classCgu_1_1Thread_1_1Mutex_1_1Lock.html" title="A scoped locking class for exception safe Mutex locking. ">Thread::Mutex::Lock</a> <a class="el" href="classCgu_1_1Thread_1_1Cond.html" title="A wrapper class for pthread condition variables. ">Thread::Cond</a> <a class="el" href="classCgu_1_1Thread_1_1Future.html" title="A class representing a pthread thread which will provide a value. ">Thread::Future</a> <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a></dd></dl>
<p>The <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> class encapsulates a pthread thread. It can start, join and cancel a thread.</p>
<p>The <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> class, and the associated <a class="el" href="classCgu_1_1Thread_1_1CancelBlock.html" title="A class enabling the cancellation state of a thread to be controlled. ">CancelBlock</a> class, can be used interchangeably with (and mixed with) GThread objects and functions, and GMutex, GStaticMutex, GStaticRecMutex and GCond, as they all use pthreads underneath on POSIX and other unix-like OSes. In addition it can be used with threads started with the C++11 threading facilities, as in C++11 on unix-like OSes these facilities will be built on top of pthreads (for which purpose C++11 provides the std::native_handle_type type and std::thread::native_handle() function). Even where they are not, they will use the same threading primitives provided by the kernel.</p>
<p><a class="anchor" id="ThreadsAnchor"></a><b>c++-gtk-utils</b> <b>library</b> <b>and</b> <b>C++11</b> <b>threads</b> </p>
<p>As mentioned above, the thread facilities provided by this library can be freely interchanged with the threading facilities provided by C++11.</p>
<p>The main features available from this library and not C++11 are thread cancellation and the associated <a class="el" href="classCgu_1_1Thread_1_1CancelBlock.html" title="A class enabling the cancellation state of a thread to be controlled. ">Cgu::Thread::CancelBlock</a> class, the <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Cgu::Thread::JoinableHandle</a> class for scoped joinable thread handling and the <a class="el" href="classCgu_1_1Thread_1_1TaskManager.html" title="A thread-pool class for managing tasks in multi-threaded programs. ">Cgu::Thread::TaskManager</a> class for running and composing tasks on a thread pool.</p>
<p>C++11 does not provide thread cancellation or interruption support, and C++ will never be able to do so on a complete basis because to do so requires support from the underlying OS, which therefore makes it platform specific (in this case, POSIX specific): cancellation is only of limited use if it cannot reliably interrupt blocking system calls. The POSIX specification sets out the interruptible cancellation points in System Interfaces, section 2.9.5, Cancellation Points, and in effect specifies all the system calls which can block as cancellation points.</p>
<p>Whether, in C++ programs, destructors of local objects in the cancelled thread are called is also system specific and is not specified by POSIX. Most modern commercial unixes, and recent linux/BSD distributions based on NPTL (in the case of Linux, those based on 2.6/3.* kernels), will unwind the stack and call destructors on thread cancellation by means of a pseudo-exception, but older distributions relying on the former linuxthreads implementation will not. Therefore for maximum portability cancellation would only be used where there are plain data structures/built-in types in existence in local scope when it occurs, and if there is anything in free store to be released some clean-ups would be implemented with pthread_cleanup_push()/pthread_cleanup_pop(). This should be controlled with pthread_setcancelstate() and/or the <a class="el" href="classCgu_1_1Thread_1_1CancelBlock.html" title="A class enabling the cancellation state of a thread to be controlled. ">CancelBlock</a> class to choose the cancellation point.</p>
<p>One of the (perhaps odd) features of C++11 threads is that if the destructor of a std::thread object is called which represents a joinable thread which has not been <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a>ed or <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a>ed, the whole program is terminated with a call to std::terminate(), which makes it difficult to use in the presence of exceptions. Often what is wanted however is for <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> to be called on a joinable thread where the associated thread object goes out of scope, or (provided it is done carefully and knowingly) for <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> to be called. The <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Cgu::Thread::JoinableHandle</a> class can be used where either of these two is the appropriate response to this situation.</p>
<p>In addition, the c++-gtk-utils library provides the following which are not present in C++11: a guaranteed monotonic clock on timed condition variable waits where the operating system supports them; read-write locks; a <a class="el" href="classCgu_1_1Thread_1_1Future.html" title="A class representing a pthread thread which will provide a value. ">Cgu::Thread::Future</a> object which is more intuitive to use than C++11 futures and features a built in <a class="el" href="namespaceCgu.html#a042105bec15e982b1a2d86b2dc4ddbbf">Cgu::SafeEmitter</a> object which emits when the particular task has completed, and (since version 2.0.2) has associated <a class="el" href="classCgu_1_1Thread_1_1Future.html#aab2d9cd3193eee443e4f6ed1d3ae6c77">Cgu::Thread::Future::when()</a> methods for passing the result to a glib main loop; and (since version 2.2.2) <a class="el" href="namespaceCgu_1_1Thread.html#a984bbff1392b7e173a8b3ad081e542c2">Cgu::Thread::parallel_for_each()</a> and <a class="el" href="namespaceCgu_1_1Thread.html#a497aa47446b79c87f1a404e11151a942">Cgu::Thread::parallel_transform()</a> functions for use with <a class="el" href="classCgu_1_1Thread_1_1TaskManager.html" title="A thread-pool class for managing tasks in multi-threaded programs. ">Cgu::Thread::TaskManager</a> objects.</p>
<p><b>c++-gtk-utils</b> <b>library</b> <b>and</b> <b>gthreads</b> </p>
<p>As mentioned above, the thread facilities provided by this library can be freely interchanged with the threading facilities provided by glib.</p>
<p>The main features available with this thread implementation and not GThreads are thread cancellation, the mutex scoped locking classes <a class="el" href="classCgu_1_1Thread_1_1Mutex_1_1Lock.html" title="A scoped locking class for exception safe Mutex locking. ">Cgu::Thread::Mutex::Lock</a> and <a class="el" href="classCgu_1_1Thread_1_1RecMutex_1_1Lock.html" title="A scoped locking class for exception safe RecMutex locking. ">Cgu::Thread::RecMutex::Lock</a>, the joinable thread scoped management class <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Cgu::Thread::JoinableHandle</a> and the <a class="el" href="classCgu_1_1Thread_1_1Future.html" title="A class representing a pthread thread which will provide a value. ">Cgu::Thread::Future</a> class (abstracting thread functions which provide a result).</p>
<p>There is no need from the perspective of this class to call g_thread_init() before <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a0c8a852f0739170f6a5ed8657031774c">Cgu::Thread::Thread::start()</a> is called, but prior to glib version 2.32 glib itself is not thread-safe without g_thread_init(), so where this class is used with glib < 2.32, g_thread_init() should be called at program initialization.</p>
<p>See <a class="el" href="Threading.html">Writing multi-threaded programs using c++-gtk-utils</a> for particulars about GTK+ thread safety. </p>
</div><h2 class="groupheader">Constructor & Destructor Documentation</h2>
<a class="anchor" id="a9d93cd72283ba3103e1695962b3840e4"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">Cgu::Thread::Thread::Thread </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a> & </td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">delete</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>This class cannot be copied: it is intended to be held by std::unique_ptr. The copy constructor is deleted. </p>
</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a class="anchor" id="a3d939f57b95a6d947c0cd339b102a189"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">void Cgu::Thread::Thread::cancel </td>
<td>(</td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">noexcept</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Cancels the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object. It can be called by any thread. The effect is undefined if the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object has both (a) already terminated and (b) been detached or had a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> made for it. Accordingly, if the user is not able to establish from the program logic whether the thread has terminated, the thread must be created as joinable and <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a3d939f57b95a6d947c0cd339b102a189">cancel()</a> must not be called after a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> has been made or a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> has returned. A <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object can used to ensure this. It does not throw. </p>
<dl class="section note"><dt>Note</dt><dd>Use this method with care - sometimes its use is unavoidable but destructors for local objects may not be called if a thread exits by virtue of a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a3d939f57b95a6d947c0cd339b102a189">cancel()</a> (that depends on the implementation). Most modern commercial unixes, and recent linux/BSD distributions based on NPTL, will unwind the stack and call destructors on thread cancellation by means of a pseudo-exception, but older distributions relying on the former linuxthreads implementation will not. Therefore for maximum portability only have plain data structures/built-in types in existence in local scope when it occurs and if there is anything in free store to be released implement some clean-ups with pthread_cleanup_push()/pthread_cleanup_pop(). This should be controlled with pthread_setcancelstate() and/or the <a class="el" href="classCgu_1_1Thread_1_1CancelBlock.html" title="A class enabling the cancellation state of a thread to be controlled. ">CancelBlock</a> class to choose the cancellation point. </dd></dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Cgu::Thread::Exit</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ae54e2ca2531928b4debbff0019ec9695"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">void Cgu::Thread::Thread::detach </td>
<td>(</td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">noexcept</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Detaches the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object where it is joinable, so as to make it unjoinable. The effect is unspecified if the thread is already unjoinable (a <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object will however give a defined result in such cases for threads originally started as joinable). It does not throw. </p>
</div>
</div>
<a class="anchor" id="a895a471861aaaad5d20ea26a256c98d1"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">bool Cgu::Thread::Thread::is_caller </td>
<td>(</td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">noexcept</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Specifies whether the calling thread is the same thread as is represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object. The effect is undefined if the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object has both (a) already terminated and (b) been detached or had a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> made for it. Accordingly, if the user is not able to establish from the program logic whether the thread has terminated, the thread must be created as joinable and <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a895a471861aaaad5d20ea26a256c98d1">is_caller()</a> must not be called after a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> has been made or a call to <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> has returned. A <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object can used to ensure this. This method does not throw. </p>
<dl class="section return"><dt>Returns</dt><dd>Returns true if the caller is in the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object. </dd></dl>
</div>
</div>
<a class="anchor" id="a91c7dc81bd997444d77185d5a5cd2fc9"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">void Cgu::Thread::Thread::join </td>
<td>(</td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">noexcept</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Joins the thread represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object (that is, waits for it to terminate). It can be called by any thread other than the one represented by this <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object. The result is undefined if the thread is or was detached or <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> has already been called for the thread (a <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object will however give a defined result in such cases for threads originally started as joinable). It does not throw. </p>
</div>
</div>
<a class="anchor" id="ae12db47abdf8ab9c5e1e9bb8ca02b036"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a>& Cgu::Thread::Thread::operator= </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classCgu_1_1Thread_1_1Thread.html">Thread</a> & </td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">delete</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>This class cannot be copied: it is intended to be held by std::unique_ptr. The assignment operator is deleted. </p>
</div>
</div>
<a class="anchor" id="a0c8a852f0739170f6a5ed8657031774c"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">static std::unique_ptr<<a class="el" href="classCgu_1_1Thread_1_1Thread.html">Cgu::Thread::Thread</a>> Cgu::Thread::Thread::start </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="namespaceCgu_1_1Callback.html#ab0fdf0ebb22f2a7cc813657f6d90a94d">Cgu::Callback::Callback</a> * </td>
<td class="paramname"><em>cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">bool </td>
<td class="paramname"><em>joinable</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Starts a new thread. It can be called by any thread. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">cb</td><td>A callback object (created by <a class="el" href="namespaceCgu_1_1Callback.html#a3e32d4f4961c618aa7e03bda00f398b8">Callback::make()</a>, <a class="el" href="namespaceCgu_1_1Callback.html#a94b122ac99f423928320240fd48d571b">Callback::make_ref()</a> or <a class="el" href="namespaceCgu_1_1Callback.html#ab0b54bd51f4ff2c80e5b593dc962be13">Callback::lambda()</a>) encapsulating the function to be executed by the new thread. The <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object returned by this function will take ownership of the callback: it will automatically be deleted either by the new thread when it has finished with it, or by this method in the calling thread if the attempt to start a new thread fails (including if std::bad_alloc is thrown). </td></tr>
<tr><td class="paramname">joinable</td><td>Whether the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> method may be called in relation to the new thread. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object representing the new thread which has been started, held by a std::unique_ptr object as it has single ownership semantics. The std::unique_ptr object will be empty (that is std::unique_ptr<Cgu::Thread::Thread>::get() will return 0) if the thread did not start correctly, which would mean that memory is exhausted, the pthread thread limit has been reached or pthread has run out of other resources to start new threads. </dd></dl>
<dl class="exception"><dt>Exceptions</dt><dd>
<table class="exception">
<tr><td class="paramname">std::bad_alloc</td><td>This method might throw std::bad_alloc if memory is exhausted and the system throws in that case. (This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system.) If this exception is thrown, the thread will not have started. </td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>1. The thread will keep running even if the return value of <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a0c8a852f0739170f6a5ed8657031774c">start()</a> goes out of scope (but it will no longer be possible to call any of the methods in this class for it, which is fine if the thread is not started as joinable and it is not intended to cancel it). </dd>
<dd>
2. If the thread is started with the joinable attribute, the user must subsequently either call the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> or the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> method, as otherwise a resource leak may occur (the destructor of this class does not call <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> automatically). Alternatively, the return value of this method can be passed to a <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object which will do this automatically in the <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object's destructor. </dd>
<dd>
3. Any <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> exception thrown from the function executed by the new thread will be caught and consumed. The thread will safely terminate and unwind the stack in so doing. </dd>
<dd>
4. If any uncaught exception other than <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> is allowed to propagate from the initial function executed by the new thread, the exception is not consumed (NPTL's forced stack unwinding on cancellation does not permit catching with an ellipsis argument without rethrowing, and even if it did permit it, the result would be an unreported error). The C++11 standard requires std::terminate() to be called in such a case and so the entire program terminated. Accordingly, a user must make sure that no exceptions, other than <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> or any cancellation pseudo-exception, can propagate from the initial function executed by the new thread. This includes ensuring that, for any argument passed to that function which is not a built-in type and which is not taken by the function by const or non-const reference, the argument type's copy constructor does not throw. </dd></dl>
</div>
</div>
<a class="anchor" id="aa7ffae4b51c245cc98bf1e029c6a900c"></a>
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class F , class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type, const Cgu::Callback::Callback*>::value>::type> </div>
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">static std::unique_ptr<<a class="el" href="classCgu_1_1Thread_1_1Thread.html">Cgu::Thread::Thread</a>> Cgu::Thread::Thread::start </td>
<td>(</td>
<td class="paramtype">F && </td>
<td class="paramname"><em>func</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">bool </td>
<td class="paramname"><em>joinable</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Starts a new thread. It can be called by any thread. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">func</td><td>A callable object, such as formed by a lambda expression or the result of std::bind, which will be executed by the new thread. </td></tr>
<tr><td class="paramname">joinable</td><td>Whether the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> method may be called in relation to the new thread. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A <a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread</a> object representing the new thread which has been started, held by a std::unique_ptr object as it has single ownership semantics. The std::unique_ptr object will be empty (that is std::unique_ptr<Cgu::Thread::Thread>::get() will return 0) if the thread did not start correctly, which would mean that memory is exhausted, the pthread thread limit has been reached or pthread has run out of other resources to start new threads. </dd></dl>
<dl class="exception"><dt>Exceptions</dt><dd>
<table class="exception">
<tr><td class="paramname">std::bad_alloc</td><td>This method might throw std::bad_alloc if memory is exhausted and the system throws in that case. (This exception will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system.) If this exception is thrown, the thread will not have started. </td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>1. This function may also throw if the copy or move constructor of the callable object throws. If that happens, the thread will not have started. </dd>
<dd>
2. The thread will keep running even if the return value of <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a0c8a852f0739170f6a5ed8657031774c">start()</a> goes out of scope (but it will no longer be possible to call any of the methods in this class for it, which is fine if the thread is not started as joinable and it is not intended to cancel it). </dd>
<dd>
3. If the thread is started with the joinable attribute, the user must subsequently either call the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#a91c7dc81bd997444d77185d5a5cd2fc9">join()</a> or the <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> method, as otherwise a resource leak may occur (the destructor of this class does not call <a class="el" href="classCgu_1_1Thread_1_1Thread.html#ae54e2ca2531928b4debbff0019ec9695">detach()</a> automatically). Alternatively, the return value of this method can be passed to a <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object which will do this automatically in the <a class="el" href="classCgu_1_1Thread_1_1JoinableHandle.html" title="A class wrapping a Thread::Thread object representing a joinable thread. ">Thread::JoinableHandle</a> object's destructor. </dd>
<dd>
4. Any <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> exception thrown from the function executed by the new thread will be caught and consumed. The thread will safely terminate and unwind the stack in so doing. </dd>
<dd>
5. If any uncaught exception other than <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> is allowed to propagate from the initial function executed by the new thread, the exception is not consumed (NPTL's forced stack unwinding on cancellation does not permit catching with an ellipsis argument without rethrowing, and even if it did permit it, the result would be an unreported error). The C++11 standard requires std::terminate() to be called in such a case and so the entire program terminated. Accordingly, a user must make sure that no exceptions, other than <a class="el" href="classCgu_1_1Thread_1_1Exit.html" title="A class which can be thrown to terminate the throwing thread. ">Thread::Exit</a> or any cancellation pseudo-exception, can propagate from the initial function executed by the new thread. This includes ensuring that, for any bound argument passed to that function which is not a built-in type and which is not taken by the function by const or non-const reference, the argument type's copy constructor does not throw.</dd></dl>
<p>Since 2.1.0 </p>
</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="thread_8h_source.html">thread.h</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Sep 16 2013 20:45:32 for c++-gtk-utils by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.4
</small></address>
</body>
</html>
