<!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::RecMutex 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_1RecMutex.html">RecMutex</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#nested-classes">Classes</a> |
<a href="#pub-methods">Public Member Functions</a> |
<a href="#pub-static-methods">Static Public Member Functions</a> |
<a href="classCgu_1_1Thread_1_1RecMutex-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">Cgu::Thread::RecMutex Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>A wrapper class for pthread mutexes which provides a recursive mutex.
<a href="classCgu_1_1Thread_1_1RecMutex.html#details">More...</a></p>
<p><code>#include <<a class="el" href="mutex_8h_source.html">c++-gtk-utils/mutex.h</a>></code></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class  </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex_1_1Lock.html">Lock</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">A scoped locking class for exception safe <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html" title="A wrapper class for pthread mutexes which provides a recursive mutex. ">RecMutex</a> locking. <a href="classCgu_1_1Thread_1_1RecMutex_1_1Lock.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class  </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex_1_1TrackLock.html">TrackLock</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">A scoped locking class for exception safe <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html" title="A wrapper class for pthread mutexes which provides a recursive mutex. ">RecMutex</a> locking which tracks the status of its mutex. <a href="classCgu_1_1Thread_1_1RecMutex_1_1TrackLock.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
</table><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:a131cdbd0aea5cfbc270701a3cd6db46f"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#a131cdbd0aea5cfbc270701a3cd6db46f">RecMutex</a> (const <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html">RecMutex</a> &)=delete</td></tr>
<tr class="separator:a131cdbd0aea5cfbc270701a3cd6db46f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:af9cb7fbb3977e74810e0f32828fc7c2c"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html">RecMutex</a> & </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#af9cb7fbb3977e74810e0f32828fc7c2c">operator=</a> (const <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html">RecMutex</a> &)=delete</td></tr>
<tr class="separator:af9cb7fbb3977e74810e0f32828fc7c2c"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:aff099ea91c91a99f64da45baa8408101"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#aff099ea91c91a99f64da45baa8408101">lock</a> () noexcept</td></tr>
<tr class="separator:aff099ea91c91a99f64da45baa8408101"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a0c2ecf413f26f645dd8ce7498a42ebe6"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#a0c2ecf413f26f645dd8ce7498a42ebe6">trylock</a> () noexcept</td></tr>
<tr class="separator:a0c2ecf413f26f645dd8ce7498a42ebe6"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a8addb58c320b88b7afd84504cbe911c0"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#a8addb58c320b88b7afd84504cbe911c0">unlock</a> () noexcept</td></tr>
<tr class="separator:a8addb58c320b88b7afd84504cbe911c0"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a3f582b0c616f862e609f6d7fb0a544fb"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#a3f582b0c616f862e609f6d7fb0a544fb">RecMutex</a> ()</td></tr>
<tr class="separator:a3f582b0c616f862e609f6d7fb0a544fb"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:abe5bbd5b68fad3c88615121ea7404d63"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#abe5bbd5b68fad3c88615121ea7404d63">~RecMutex</a> ()</td></tr>
<tr class="separator:abe5bbd5b68fad3c88615121ea7404d63"><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:ab871e0ef7a8cc56f77009c3b5287800e"><td class="memItemLeft" align="right" valign="top">static int </td><td class="memItemRight" valign="bottom"><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#ab871e0ef7a8cc56f77009c3b5287800e">test_support</a> ()</td></tr>
<tr class="separator:ab871e0ef7a8cc56f77009c3b5287800e"><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 wrapper class for pthread mutexes which provides a recursive mutex. </p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classCgu_1_1Thread_1_1Thread.html" title="A class representing a pthread thread. ">Thread::Thread</a> <a class="el" href="classCgu_1_1Thread_1_1RecMutex_1_1Lock.html" title="A scoped locking class for exception safe RecMutex locking. ">Thread::RecMutex::Lock</a> <a class="el" href="classCgu_1_1Thread_1_1RecMutex_1_1TrackLock.html" title="A scoped locking class for exception safe RecMutex locking which tracks the status of its mutex...">Thread::RecMutex::TrackLock</a> <a class="el" href="classCgu_1_1Thread_1_1Mutex.html" title="A wrapper class for pthread mutexes. ">Thread::Mutex</a></dd></dl>
<p>This class can be used interchangeably with threads started with GThread and by this library, as both glib and this library use pthreads underneath on POSIX and other unix-like OSes. It can also be used interchangeably with those started by C++11 and with std::recursive_mutex and similar objects, 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), or if they are not, they will use the same threading primitives provided by the kernel.</p>
<p><a class="el" href="classCgu_1_1Thread_1_1RecMutex.html" title="A wrapper class for pthread mutexes which provides a recursive mutex. ">RecMutex</a> objects can be constructed statically as well as dynamically and there is no need to call g_thread_init() before they are constructed, even if glib < 2.32 is used. (If created as a static object in global scope, it will not be possible to catch <a class="el" href="structCgu_1_1Thread_1_1MutexError.html">Thread::MutexError</a> or <a class="el" href="structCgu_1_1Thread_1_1RecMutexError.html">Thread::RecMutexError</a> thrown by its constructor, but if a static global mutex throws there is nothing that could be done anyway except abort.)</p>
<p>See the comments below on the <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#ab871e0ef7a8cc56f77009c3b5287800e">test_support()</a> method of this class, about how the system's support for native recursive mutexes can be tested at runtime and when a user program is compiled. If glib >= 2.32 is installed, it can be assumed that native recursive mutexes are available, as glib >= 2.32 also uses them. </p>
</div><h2 class="groupheader">Constructor & Destructor Documentation</h2>
<a class="anchor" id="a131cdbd0aea5cfbc270701a3cd6db46f"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">Cgu::Thread::RecMutex::RecMutex </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html">RecMutex</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. The copy constructor is deleted. </p>
</div>
</div>
<a class="anchor" id="a3f582b0c616f862e609f6d7fb0a544fb"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Cgu::Thread::RecMutex::RecMutex </td>
<td>(</td>
<td class="paramname">)</td><td></td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Initialises the pthread mutex. It is not a cancellation point. </p>
<dl class="exception"><dt>Exceptions</dt><dd>
<table class="exception">
<tr><td class="paramname"><a class="el" href="structCgu_1_1Thread_1_1RecMutexError.html">Cgu::Thread::RecMutexError</a></td><td>Throws this exception if the system does not support recursive mutexes. (If this has been checked beforehand, say by calling <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html#ab871e0ef7a8cc56f77009c3b5287800e">test_support()</a>, there should be no need to check for this exception.) </td></tr>
<tr><td class="paramname"><a class="el" href="structCgu_1_1Thread_1_1MutexError.html">Cgu::Thread::MutexError</a></td><td>Throws this exception if initialization of the mutex fails, except because the system does not support recursive mutexes. (It is often not worth checking for <a class="el" href="structCgu_1_1Thread_1_1MutexError.html">MutexError</a>, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.) </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="abe5bbd5b68fad3c88615121ea7404d63"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">Cgu::Thread::RecMutex::~RecMutex </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> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Destroys the pthread mutex. It is not a cancellation point. It does not throw. Destroying a mutex which is currently locked results in undefined behavior. </p>
</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a class="anchor" id="aff099ea91c91a99f64da45baa8408101"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">int Cgu::Thread::RecMutex::lock </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>Locks the mutex and acquires ownership. Blocks if already locked until it becomes free, unless the calling thread already holds the lock, in which case it increments the lock count and returns immediately. It is not a cancellation point. It does not throw. It is thread safe. </p>
<dl class="section return"><dt>Returns</dt><dd>0 if successful, otherwise the pthread mutex error number. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>With this library implementation, the only pthread error number which could be returned by this method is EAGAIN, which it would do if the maximum recursive lock count for this mutex has been reached. Usually this number is at or around INT_MAX and hence the return value is usually not worth checking for except during debugging. </dd></dl>
</div>
</div>
<a class="anchor" id="af9cb7fbb3977e74810e0f32828fc7c2c"></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_1RecMutex.html">RecMutex</a>& Cgu::Thread::RecMutex::operator= </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classCgu_1_1Thread_1_1RecMutex.html">RecMutex</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. The assignment operator is deleted. </p>
</div>
</div>
<a class="anchor" id="ab871e0ef7a8cc56f77009c3b5287800e"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">static int Cgu::Thread::RecMutex::test_support </td>
<td>(</td>
<td class="paramname">)</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>Indicates whether the system supports recursive mutexes. This method does not throw. It is thread safe. </p>
<dl class="section return"><dt>Returns</dt><dd>0 if the system supports recursive mutexes, -1 if it does not support recursive mutexes and 1 if pthread has run out of sufficient resources to test this at run time (in which case any attempt to create mutexes or start threads is likely to fail). Practically all recent linux and BSD distributions will support them, and this function would normally return 0. If it does not, it is still possible to use GStaticRecMutex objects (for which purpose see <a class="el" href="classCgu_1_1Thread_1_1GrecmutexLock.html" title="A scoped locking class for exception safe locking of GStaticRecMutex objects. ">Cgu::Thread::GrecmutexLock</a>).</dd></dl>
<dl class="section note"><dt>Note</dt><dd>The header file <c++-gtk-utils/cgu_config.h> defines the symbol CGU_HAVE_RECURSIVE_MUTEX if native recursive mutexes were found to be supported when this library was compiled. Programs using this library can therefore test for that symbol with the pre-processor for conditional compilation purposes (so that the program can, for example, be compiled to use GStaticRecMutex if that symbol is not defined). However, if the library was cross-compiled from one architecture to another, that symbol may not be defined even though the target architecture does, in fact, support them at program runtime. In other words, if CGU_HAVE_RECURSIVE_MUTEX is defined then this method will always return 0; but in the event of cross-compilation of the library this method (which provides a separate runtime test) might return 0, correctly showing support, even when CGU_HAVE_RECURSIVE_MUTEX is not defined.</dd>
<dd>
If glib >= 2.32 is installed, it can be assumed that native recursive mutexes are available, as glib >= 2.32 also uses them. </dd></dl>
</div>
</div>
<a class="anchor" id="a0c2ecf413f26f645dd8ce7498a42ebe6"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">int Cgu::Thread::RecMutex::trylock </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>Tries to lock the mutex and acquire ownership, but returns immediately if it is already locked with value EBUSY unless the calling thread already holds the lock, in which case it returns normally and increments the lock count. It is not a cancellation point. It does not throw. It is thread safe. </p>
<dl class="section return"><dt>Returns</dt><dd>0 if successful, otherwise EBUSY or other pthread mutex error number. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>With this library implementation, apart from EBUSY, the only other pthread error number which could be returned by this method is EAGAIN, which it would do if the maximum recursive lock count for this mutex has been reached. Usually this number is at or around INT_MAX and hence an EAGAIN error return value is usually not worth checking for except during debugging. </dd></dl>
</div>
</div>
<a class="anchor" id="a8addb58c320b88b7afd84504cbe911c0"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">int Cgu::Thread::RecMutex::unlock </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>Unlocks a locked mutex owned by the calling thread and either relinquishes ownership (if the mutex has not been recursively locked) or decrements the lock count (if it has). It is not a cancellation point. It does not throw. It must be called by the thread which owns the mutex. </p>
<dl class="section return"><dt>Returns</dt><dd>0 if successful, otherwise the pthread mutex error number. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>With this library implementation, the only pthread error number which could be returned by this method is EPERM because the calling thread does not own the mutex (however POSIX does not require that return value in that case and hence the return value is usually not worth checking for except during debugging). </dd></dl>
</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="mutex_8h_source.html">mutex.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>
