<!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"/>
<title>GNU CommonC++: ost::Mutex Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</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>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<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 class="navpath"><a class="el" href="namespaceost.html">ost</a>::<a class="el" href="classost_1_1_mutex.html">Mutex</a>
</div>
</div>
<div class="contents">
<h1>ost::Mutex Class Reference</h1><!-- doxytag: class="ost::Mutex" -->
<p>The <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> class is used to protect a section of code so that at any given time only a single thread can perform the protected operation.
<a href="#_details">More...</a></p>
<p><code>#include <<a class="el" href="thread_8h_source.html">thread.h</a>></code></p>
<div class="dynheader">
Inheritance diagram for ost::Mutex:</div>
<div class="dynsection">
<div class="center">
<img src="classost_1_1_mutex.png" usemap="#ost::Mutex_map" alt=""/>
<map id="ost::Mutex_map" name="ost::Mutex_map">
<area href="classost_1_1_map_table.html" alt="ost::MapTable" shape="rect" coords="146,56,282,80"/>
<area href="classost_1_1_mutex_counter.html" alt="ost::MutexCounter" shape="rect" coords="146,112,282,136"/>
<area href="classost_1_1_random_file.html" alt="ost::RandomFile" shape="rect" coords="146,168,282,192"/>
<area href="classost_1_1_runlist.html" alt="ost::Runlist" shape="rect" coords="146,224,282,248"/>
<area href="classost_1_1_serial_service.html" alt="ost::SerialService" shape="rect" coords="146,280,282,304"/>
<area href="classost_1_1_shared_mem_pager.html" alt="ost::SharedMemPager" shape="rect" coords="146,336,282,360"/>
<area href="classost_1_1_socket_service.html" alt="ost::SocketService" shape="rect" coords="146,392,282,416"/>
<area href="classost_1_1_thread_queue.html" alt="ost::ThreadQueue" shape="rect" coords="146,448,282,472"/>
</map>
</div>
</div>
<p><a href="classost_1_1_mutex-members.html">List of all members.</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#a22e6ce5d9d8d209dac70e39310459202">Mutex</a> (const char *name=NULL)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The mutex is always initialized as a recursive entity. <a href="#a22e6ce5d9d8d209dac70e39310459202"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#a5ccc1c2e7278d8adc47fd728706c33a8">~Mutex</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Destroying the mutex removes any system resources associated with it. <a href="#a5ccc1c2e7278d8adc47fd728706c33a8"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#abed8b05b63f9cdd2c9ca1f92081b1a8a">nameMutex</a> (const char *name)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Enable setting of mutex name for deadlock debug. <a href="#abed8b05b63f9cdd2c9ca1f92081b1a8a"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#adc1471d0c2114e5c49e1fe7152448378">enterMutex</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Entering a <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> locks the mutex for the current thread. <a href="#adc1471d0c2114e5c49e1fe7152448378"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#aecb516325583e432bf2bf7e4b565f6f6">enter</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Future abi will use enter/leave/test members. <a href="#aecb516325583e432bf2bf7e4b565f6f6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#ab6aaecac9c95d31a5862014d7f1afe73">leave</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Future abi will use enter/leave/test members. <a href="#ab6aaecac9c95d31a5862014d7f1afe73"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#ac1ff5454b2c9b55790c4bf33f751704c">test</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Future abi will use enter/leave/test members. <a href="#ac1ff5454b2c9b55790c4bf33f751704c"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#aa46b490ac92017ef89980b0020bff8c0">tryEnterMutex</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Tries to lock the mutex for the current thread. <a href="#aa46b490ac92017ef89980b0020bff8c0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#a403208d275c4c7b8087a40259b0cb0f3">leaveMutex</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Leaving a mutex frees that mutex for use by another thread. <a href="#a403208d275c4c7b8087a40259b0cb0f3"></a><br/></td></tr>
<tr><td colspan="2"><h2>Static Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static void </td><td class="memItemRight" valign="bottom"><a class="el" href="classost_1_1_mutex.html#a83b66f786e344b5192a3993d319aa735">setDebug</a> (bool mode)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Enable or disable deadlock debugging. <a href="#a83b66f786e344b5192a3993d319aa735"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>The <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> class is used to protect a section of code so that at any given time only a single thread can perform the protected operation. </p>
<p>The <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> can be used as a base class to protect access in a derived class. When used in this manner, the ENTER_CRITICAL and LEAVE_CRITICAL macros can be used to specify when code written for the derived class needs to be protected by the default <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> of the derived class, and hence is presumed to be 'thread safe' from multiple instance execution. One of the most basic Common C++ synchronization object is the <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> class. A <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> only allows one thread to continue execution at a given time over a specific section of code. Mutex's have a enter and leave method; only one thread can continue from the Enter until the Leave is called. The next thread waiting can then get through. Mutex's are also known as "CRITICAL SECTIONS" in win32-speak.</p>
<p>The <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> is always recursive in that if the same thread invokes the same mutex lock multiple times, it must release it multiple times. This allows a function to call another function which also happens to use the same mutex lock when called directly. This was deemed essential because a mutex might be used to block individual file requests in say, a database, but the same mutex might be needed to block a whole series of database updates that compose a "transaction" for one thread to complete together without having to write alternate non-locking member functions to invoke for each part of a transaction.</p>
<p>Strangely enough, the original pthread draft standard does not directly support recursive mutexes. In fact this is the most common "NP" extension for most pthread implementations. Common C++ emulates recursive mutex behavior when the target platform does not directly support it.</p>
<p>In addition to the <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a>, Common C++ supports a rwlock class. This implements the X/Open recommended "rwlock". On systems which do not support rwlock's, the behavior is emulated with a <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a>; however, the advantage of a rwlock over a mutex is then entirely lost. There has been some suggested clever hacks for "emulating" the behavior of a rwlock with a pair of mutexes and a semaphore, and one of these will be adapted for Common C++ in the future for platforms that do not support rwlock's directly.</p>
<dl class="author"><dt><b>Author:</b></dt><dd>David Sugar <<a href="mailto:dyfet@ostel.com">dyfet@ostel.com</a>> <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> lock for protected access. </dd></dl>
<dl><dt><b>Examples: </b></dt><dd>
<p><a class="el" href="tcpservice_8cpp-example.html#_a0">tcpservice.cpp</a>, and <a class="el" href="tcpthread_8cpp-example.html#_a6">tcpthread.cpp</a>.</p>
</dd>
</dl><hr/><h2>Constructor & Destructor Documentation</h2>
<a class="anchor" id="a22e6ce5d9d8d209dac70e39310459202"></a><!-- doxytag: member="ost::Mutex::Mutex" ref="a22e6ce5d9d8d209dac70e39310459202" args="(const char *name=NULL)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ost::Mutex::Mutex </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name</em> = <code>NULL</code></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>The mutex is always initialized as a recursive entity. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>of mutex for optional deadlock detection </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a5ccc1c2e7278d8adc47fd728706c33a8"></a><!-- doxytag: member="ost::Mutex::~Mutex" ref="a5ccc1c2e7278d8adc47fd728706c33a8" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual ost::Mutex::~Mutex </td>
<td>(</td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destroying the mutex removes any system resources associated with it. </p>
<p>If a mutex lock is currently in place, it is presumed to terminate when the <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> is destroyed. </p>
</div>
</div>
<hr/><h2>Member Function Documentation</h2>
<a class="anchor" id="aecb516325583e432bf2bf7e4b565f6f6"></a><!-- doxytag: member="ost::Mutex::enter" ref="aecb516325583e432bf2bf7e4b565f6f6" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ost::Mutex::enter </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Future abi will use enter/leave/test members. </p>
</div>
</div>
<a class="anchor" id="adc1471d0c2114e5c49e1fe7152448378"></a><!-- doxytag: member="ost::Mutex::enterMutex" ref="adc1471d0c2114e5c49e1fe7152448378" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ost::Mutex::enterMutex </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Entering a <a class="el" href="classost_1_1_mutex.html" title="The Mutex class is used to protect a section of code so that at any given time only...">Mutex</a> locks the mutex for the current thread. </p>
<p>This also can be done using the ENTER_CRITICAL macro or by using the ++ operator on a mutex.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classost_1_1_mutex.html#a403208d275c4c7b8087a40259b0cb0f3" title="Leaving a mutex frees that mutex for use by another thread.">leaveMutex</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ab6aaecac9c95d31a5862014d7f1afe73"></a><!-- doxytag: member="ost::Mutex::leave" ref="ab6aaecac9c95d31a5862014d7f1afe73" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ost::Mutex::leave </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Future abi will use enter/leave/test members. </p>
</div>
</div>
<a class="anchor" id="a403208d275c4c7b8087a40259b0cb0f3"></a><!-- doxytag: member="ost::Mutex::leaveMutex" ref="a403208d275c4c7b8087a40259b0cb0f3" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ost::Mutex::leaveMutex </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Leaving a mutex frees that mutex for use by another thread. </p>
<p>If the mutex has been entered (invoked) multiple times (recursivily) by the same thread, then it will need to be exited the same number of instances before it is free for re-use. This operation can also be done using the LEAVE_CRITICAL macro or by the -- operator on a mutex.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classost_1_1_mutex.html#adc1471d0c2114e5c49e1fe7152448378" title="Entering a Mutex locks the mutex for the current thread.">enterMutex</a> </dd></dl>
</div>
</div>
<a class="anchor" id="abed8b05b63f9cdd2c9ca1f92081b1a8a"></a><!-- doxytag: member="ost::Mutex::nameMutex" ref="abed8b05b63f9cdd2c9ca1f92081b1a8a" args="(const char *name)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ost::Mutex::nameMutex </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name</em></td>
<td> ) </td>
<td><code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Enable setting of mutex name for deadlock debug. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>for mutex. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a83b66f786e344b5192a3993d319aa735"></a><!-- doxytag: member="ost::Mutex::setDebug" ref="a83b66f786e344b5192a3993d319aa735" args="(bool mode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static void ost::Mutex::setDebug </td>
<td>(</td>
<td class="paramtype">bool </td>
<td class="paramname"> <em>mode</em></td>
<td> ) </td>
<td><code> [inline, static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Enable or disable deadlock debugging. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>mode</em> </td><td>debug mode. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ac1ff5454b2c9b55790c4bf33f751704c"></a><!-- doxytag: member="ost::Mutex::test" ref="ac1ff5454b2c9b55790c4bf33f751704c" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool ost::Mutex::test </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td><code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Future abi will use enter/leave/test members. </p>
<dl class="return"><dt><b>Returns:</b></dt><dd>true if entered. </dd></dl>
</div>
</div>
<a class="anchor" id="aa46b490ac92017ef89980b0020bff8c0"></a><!-- doxytag: member="ost::Mutex::tryEnterMutex" ref="aa46b490ac92017ef89980b0020bff8c0" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool ost::Mutex::tryEnterMutex </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Tries to lock the mutex for the current thread. </p>
<p>Behaves like <a class="el" href="classost_1_1_mutex.html#adc1471d0c2114e5c49e1fe7152448378" title="Entering a Mutex locks the mutex for the current thread.">enterMutex</a> , except that it doesn't block the calling thread if the mutex is already locked by another thread.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>true if locking the mutex was succesful otherwise false</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classost_1_1_mutex.html#adc1471d0c2114e5c49e1fe7152448378" title="Entering a Mutex locks the mutex for the current thread.">enterMutex</a> </dd>
<dd>
<a class="el" href="classost_1_1_mutex.html#a403208d275c4c7b8087a40259b0cb0f3" title="Leaving a mutex frees that mutex for use by another thread.">leaveMutex</a> </dd></dl>
</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>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Fri Nov 12 09:57:40 2010 for GNU CommonC++ by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
main-updates
>
by-pkgid
>
f36f42783f75191f5f2d47f1e8c5504e
>
files
>
268
