<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QSystemSemaphore Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QSystemSemaphore Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QSystemSemaphore class provides a general counting system
semaphore. <a href="#details">More...</a></p>
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qsystemsemaphore.html#AccessMode-enum">AccessMode</a></b> { Open, Create }</li><li><div class="fn" />enum <b><a href="qsystemsemaphore.html#SystemSemaphoreError-enum">SystemSemaphoreError</a></b> { NoError, PermissionDenied, KeyError, AlreadyExists, ..., UnknownError }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qsystemsemaphore.html#QSystemSemaphore">__init__</a></b> (<i>self</i>, QString <i>key</i>, int <i>initialValue</i> = 0, AccessMode <i>mode</i> = QSystemSemaphore.Open)</li><li><div class="fn" />bool <b><a href="qsystemsemaphore.html#acquire">acquire</a></b> (<i>self</i>)</li><li><div class="fn" />SystemSemaphoreError <b><a href="qsystemsemaphore.html#error">error</a></b> (<i>self</i>)</li><li><div class="fn" />QString <b><a href="qsystemsemaphore.html#errorString">errorString</a></b> (<i>self</i>)</li><li><div class="fn" />QString <b><a href="qsystemsemaphore.html#key">key</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qsystemsemaphore.html#release">release</a></b> (<i>self</i>, int <i>n</i> = 1)</li><li><div class="fn" /><b><a href="qsystemsemaphore.html#setKey">setKey</a></b> (<i>self</i>, QString <i>key</i>, int <i>initialValue</i> = 0, AccessMode <i>mode</i> = QSystemSemaphore.Open)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QSystemSemaphore class provides a general counting system
semaphore.</p>
<p>A semaphore is a generalization of a mutex. While a mutex can be
locked only once, a semaphore can be acquired multiple times.
Typically, a semaphore is used to protect a certain number of
identical resources.</p>
<p>Like its lighter counterpart <a href="qsemaphore.html">QSemaphore</a>, a QSystemSemaphore can be
accessed from multiple <a href="qthread.html">threads</a>. Unlike
<a href="qsemaphore.html">QSemaphore</a>, a QSystemSemaphore can
also be accessed from multiple <a href="qprocess.html">processes</a>. This means QSystemSemaphore is a
much heavier class, so if your application doesn't need to access
your semaphores across multiple processes, you will probably want
to use <a href="qsemaphore.html">QSemaphore</a>.</p>
<p>Semaphores support two fundamental operations, <a href="qsystemsemaphore.html#acquire">acquire</a>() and <a href="qsystemsemaphore.html#release">release</a>():</p>
<p><a href="qsystemsemaphore.html#acquire">acquire</a>() tries to
acquire one resource. If there isn't a resource available, the call
blocks until a resource becomes available. Then the resource is
acquired and the call returns.</p>
<p><a href="qsystemsemaphore.html#release">release</a>() releases
one resource so it can be acquired by another process. The function
can also be called with a parameter n > 1, which releases n
resources.</p>
<p>A system semaphore is created with a string key that other
processes can use to use the same semaphore.</p>
<p>Example: Create a system semaphore</p>
<pre class="cpp">
<span class="type">QSystemSemaphore</span> sem(<span class="string">"market"</span><span class="operator">,</span> <span class="number">3</span><span class="operator">,</span> <span class="type">QSystemSemaphore</span><span class="operator">.</span>Create);
<span class="comment">// resources available == 3</span>
sem<span class="operator">.</span><a href="qsystemsemaphore.html#acquire">acquire</a>(); <span class="comment">// resources available == 2</span>
sem<span class="operator">.</span><a href="qsystemsemaphore.html#acquire">acquire</a>(); <span class="comment">// resources available == 1</span>
sem<span class="operator">.</span><a href="qsystemsemaphore.html#acquire">acquire</a>(); <span class="comment">// resources available == 0</span>
sem<span class="operator">.</span><a href="qsystemsemaphore.html#release">release</a>(); <span class="comment">// resources available == 1</span>
sem<span class="operator">.</span><a href="qsystemsemaphore.html#release">release</a>(<span class="number">2</span>); <span class="comment">// resources available == 3</span>
</pre>
<p>A typical application of system semaphores is for controlling
access to a circular buffer shared by a producer process and a
consumer processes.</p>
<a id="platform-specific-behavior" name="platform-specific-behavior" />
<h3>Platform-Specific Behavior</h3>
<p>When using this class, be aware of the following platform
differences:</p>
<p><b>Windows:</b> QSystemSemaphore does not own its underlying
system semaphore. Windows owns it. This means that when all
instances of QSystemSemaphore for a particular key have been
destroyed, either by having their destructors called, or because
one or more processes crash, Windows removes the underlying system
semaphore.</p>
<p><b>Unix:</b></p>
<ul>
<li>QSystemSemaphore owns the underlying system semaphore in Unix
systems. This means that the last process having an instance of
QSystemSemaphore for a particular key must remove the underlying
system semaphore in its destructor. If the last process crashes
without running the QSystemSemaphore destructor, Unix does not
automatically remove the underlying system semaphore, and the
semaphore survives the crash. A subsequent process that constructs
a QSystemSemaphore with the same key will then be given the
existing system semaphore. In that case, if the QSystemSemaphore
constructor has specified its <a href="qsystemsemaphore.html#AccessMode-enum">access mode</a> as <a href="qsystemsemaphore.html#AccessMode-enum">Open</a>, its initial
resource count will not be reset to the one provided but remain set
to the value it received in the crashed process. To protect against
this, the first process to create a semaphore for a particular key
(usually a server), must pass its <a href="qsystemsemaphore.html#AccessMode-enum">access mode</a> as <a href="qsystemsemaphore.html#AccessMode-enum">Create</a>, which will
force Unix to reset the resource count in the underlying system
semaphore.</li>
<li>When a process using QSystemSemaphore terminates for any
reason, Unix automatically reverses the effect of all acquire
operations that were not released. Thus if the process acquires a
resource and then exits without releasing it, Unix will release
that resource.</li>
<li>Symbian: QSystemSemaphore behaves the same as Windows
semaphores. In other words, the operating system owns the semaphore
and ignores <a href="qsystemsemaphore.html#AccessMode-enum">QSystemSemaphore.AccessMode</a>.</li>
</ul>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="AccessMode-enum" />QSystemSemaphore.AccessMode</h3><p>This enum is used by the constructor and <a href="qsystemsemaphore.html#setKey">setKey</a>(). Its purpose is to
enable handling the problem in Unix implementations of semaphores
that survive a crash. In Unix, when a semaphore survives a crash,
we need a way to force it to reset its resource count, when the
system reuses the semaphore. In Windows and in Symbian, where
semaphores can't survive a crash, this enum has no effect.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.Open</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">If the semaphore already exists, its initial
resource count is not reset. If the semaphore does not already
exist, it is created and its initial resource count set.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.Create</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign"><a href="qsystemsemaphore.html">QSystemSemaphore</a> takes ownership of the
semaphore and sets its resource count to the requested value,
regardless of whether the semaphore already exists by having
survived a crash. This value should be passed to the constructor,
when the first semaphore for a particular key is constructed and
you know that if the semaphore already exists it could only be
because of a crash. In Windows and in Symbian, where a semaphore
can't survive a crash, Create and Open have the same behavior.</td>
</tr>
</table>
<h3 class="fn"><a name="SystemSemaphoreError-enum" />QSystemSemaphore.SystemSemaphoreError</h3><table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.NoError</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">No error occurred.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QSystemSemaphore.PermissionDenied</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The operation failed because the caller didn't
have the required permissions.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.KeyError</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The operation failed because of an invalid
key.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.AlreadyExists</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">The operation failed because a system
semaphore with the specified key already existed.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.NotFound</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">The operation failed because a system
semaphore with the specified key could not be found.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.OutOfResources</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">The operation failed because there was not
enough memory available to fill the request.</td>
</tr>
<tr>
<td class="topAlign"><tt>QSystemSemaphore.UnknownError</tt></td>
<td class="topAlign"><tt>6</tt></td>
<td class="topAlign">Something else happened and it was bad.</td>
</tr>
</table>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QSystemSemaphore" />QSystemSemaphore.__init__ (<i>self</i>, QString <i>key</i>, int <i>initialValue</i> = 0, <a href="qsystemsemaphore.html#AccessMode-enum">AccessMode</a> <i>mode</i> = QSystemSemaphore.Open)</h3><p>Requests a system semaphore for the specified <i>key</i>. The
parameters <i>initialValue</i> and <i>mode</i> are used according
to the following rules, which are system dependent.</p>
<p>In Unix, if the <i>mode</i> is <a href="qsystemsemaphore.html#AccessMode-enum">Open</a> and the system
already has a semaphore identified by <i>key</i>, that semaphore is
used, and the semaphore's resource count is not changed, i.e.,
<i>initialValue</i> is ignored. But if the system does not already
have a semaphore identified by <i>key</i>, it creates a new
semaphore for that key and sets its resource count to
<i>initialValue</i>.</p>
<p>In Unix, if the <i>mode</i> is <a href="qsystemsemaphore.html#AccessMode-enum">Create</a> and the system
already has a semaphore identified by <i>key</i>, that semaphore is
used, and its resource count is set to <i>initialValue</i>. If the
system does not already have a semaphore identified by <i>key</i>,
it creates a new semaphore for that key and sets its resource count
to <i>initialValue</i>.</p>
<p>In QNX, if the <i>mode</i> is <a href="qsystemsemaphore.html#AccessMode-enum">Create</a> and the system
already has a semaphore identified by <i>key</i>, that semaphore
will be deleted and the new one will be created for that key with a
resource count set to <i>initialValue</i>.</p>
<p>In Windows and in Symbian, <i>mode</i> is ignored, and the
system always tries to create a semaphore for the specified
<i>key</i>. If the system does not already have a semaphore
identified as <i>key</i>, it creates the semaphore and sets its
resource count to <i>initialValue</i>. But if the system already
has a semaphore identified as <i>key</i> it uses that semaphore and
ignores <i>initialValue</i>.</p>
<p>The <a href="qsystemsemaphore.html#AccessMode-enum">mode</a>
parameter is only used in Unix systems to handle the case where a
semaphore survives a process crash. In that case, the next process
to allocate a semaphore with the same <i>key</i> will get the
semaphore that survived the crash, and unless <i>mode</i> is
<a href="qsystemsemaphore.html#AccessMode-enum">Create</a>, the
resource count will not be reset to <i>initialValue</i> but will
retain the initial value it had been given by the crashed
process.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#acquire">acquire</a>() and <a href="qsystemsemaphore.html#key">key</a>().</p>
<h3 class="fn"><a name="acquire" />bool QSystemSemaphore.acquire (<i>self</i>)</h3><p>Acquires one of the resources guarded by this semaphore, if
there is one available, and returns true. If all the resources
guarded by this semaphore have already been acquired, the call
blocks until one of them is released by another process or thread
having a semaphore with the same key.</p>
<p>If false is returned, a system error has occurred. Call <a href="qsystemsemaphore.html#error">error</a>() to get a value of
<a href="qsystemsemaphore.html#SystemSemaphoreError-enum">QSystemSemaphore.SystemSemaphoreError</a>
that indicates which error occurred.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#release">release</a>().</p>
<h3 class="fn"><a name="error" /><a href="qsystemsemaphore.html#SystemSemaphoreError-enum">SystemSemaphoreError</a> QSystemSemaphore.error (<i>self</i>)</h3><p>Returns a value indicating whether an error occurred, and, if
so, which error it was.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#errorString">errorString</a>().</p>
<h3 class="fn"><a name="errorString" />QString QSystemSemaphore.errorString (<i>self</i>)</h3><p>Returns a text description of the last error that occurred. If
<a href="qsystemsemaphore.html#error">error</a>() returns an
<a href="qsystemsemaphore.html#SystemSemaphoreError-enum">error
value</a>, call this function to get a text string that describes
the error.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#error">error</a>().</p>
<h3 class="fn"><a name="key" />QString QSystemSemaphore.key (<i>self</i>)</h3><p>Returns the key assigned to this system semaphore. The key is
the name by which the semaphore can be accessed from other
processes.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#setKey">setKey</a>().</p>
<h3 class="fn"><a name="release" />bool QSystemSemaphore.release (<i>self</i>, int <i>n</i> = 1)</h3><p>Releases <i>n</i> resources guarded by the semaphore. Returns
true unless there is a system error.</p>
<p>Example: Create a system semaphore having five resources;
acquire them all and then release them all.</p>
<pre class="cpp">
<span class="type"><a href="qsystemsemaphore.html">QSystemSemaphore</a></span> sem(<span class="string">"market"</span><span class="operator">,</span> <span class="number">5</span><span class="operator">,</span> <span class="type"><a href="qsystemsemaphore.html">QSystemSemaphore</a></span><span class="operator">.</span>Create);
sem<span class="operator">.</span><a href="qsystemsemaphore.html#acquire">acquire</a>(<span class="number">5</span>); <span class="comment">// acquire all 5 resources</span>
sem<span class="operator">.</span>release(<span class="number">5</span>); <span class="comment">// release the 5 resources</span>
</pre>
<p>This function can also "create" resources. For example,
immediately following the sequence of statements above, suppose we
add the statement:</p>
<pre class="cpp">
sem<span class="operator">.</span>release(<span class="number">10</span>); <span class="comment">// "create" 10 new resources</span>
</pre>
<p>Ten new resources are now guarded by the semaphore, in addition
to the five that already existed. You would not normally use this
function to create more resources.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#acquire">acquire</a>().</p>
<h3 class="fn"><a name="setKey" />QSystemSemaphore.setKey (<i>self</i>, QString <i>key</i>, int <i>initialValue</i> = 0, <a href="qsystemsemaphore.html#AccessMode-enum">AccessMode</a> <i>mode</i> = QSystemSemaphore.Open)</h3><p>This function works the same as the constructor. It reconstructs
this <a href="qsystemsemaphore.html">QSystemSemaphore</a> object.
If the new <i>key</i> is different from the old key, calling this
function is like calling the destructor of the semaphore with the
old key, then calling the constructor to create a new semaphore
with the new <i>key</i>. The <i>initialValue</i> and <i>mode</i>
parameters are as defined for the constructor.</p>
<p><b>See also</b> <a href="qsystemsemaphore.html#QSystemSemaphore">QSystemSemaphore</a>() and
<a href="qsystemsemaphore.html#key">key</a>().</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
