<class name="QSemaphore" doc="/** <p>The <a href="QSemaphore.html#QSemaphore(int)"><tt>QSemaphore</tt></a> class provides a general counting semaphore.</p> <p>A semaphore is a generalization of a mutex. While a mutex can only be locked once, it's possible to acquire a semaphore multiple times. Semaphores are typically used to protect a certain number of identical resources.</p> <p>Semaphores support two fundamental operations, <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a> and <a href="QSemaphore.html#release(int)"><tt>release</tt></a>:</p> <ul> <li>acquire(<i>n</i>) tries to acquire <i>n</i> resources. If there aren't that many resources available, the call will block until this is the case.</li> <li>release(<i>n</i>) releases <i>n</i> resources.</li> </ul> <p>There's also a <a href="QSemaphore.html#tryAcquire(int, int)"><tt>tryAcquire</tt></a> function that returns immediately if it cannot acquire the resources, and an <a href="QSemaphore.html#available()"><tt>available</tt></a> function that returns the number of available resources at any time.</p> <p>Example:</p> <pre> QSemaphore sem(5); <span class="comment">// sem.available() == 5</span> sem.acquire(3); <span class="comment">// sem.available() == 2</span> sem.acquire(2); <span class="comment">// sem.available() == 0</span> sem.release(5); <span class="comment">// sem.available() == 5</span> sem.release(5); <span class="comment">// sem.available() == 10</span> sem.tryAcquire(1); <span class="comment">// sem.available() == 9, returns true</span> sem.tryAcquire(250); <span class="comment">// sem.available() == 9, returns false</span></pre> <p>A typical application of semaphores is for controlling access to a circular buffer shared by a producer thread and a consumer thread. The Semaphores</tt> example shows how to use <a href="QSemaphore.html#QSemaphore(int)"><tt>QSemaphore</tt></a> to solve that problem.</p> <p>A non-computing example of a semaphore would be dining at a restaurant. A semaphore is initialized with the number of chairs in the restaurant. As people arrive, they want a seat. As seats are filled, <a href="QSemaphore.html#available()"><tt>available</tt></a> is decremented. As people leave, the <a href="QSemaphore.html#available()"><tt>available</tt></a> is incremented, allowing more people to enter. If a party of 10 people want to be seated, but there are only 9 seats, those 10 people will wait, but a party of 4 people would be seated (taking the available seats to 5, making the party of 10 people wait longer).</p> @see <a href="QMutex.html"><tt>QMutex</tt></a> @see <a href="QWaitCondition.html"><tt>QWaitCondition</tt></a> @see <tt>QThread</tt> @see Semaphores Example</tt> */"> <method name="public QSemaphore(int n)" doc="/** <p>Creates a new semaphore and initializes the number of resources it guards to <tt>n</tt> (by default, 0).</p> @see <a href="QSemaphore.html#release(int)"><tt>release</tt></a> @see <a href="QSemaphore.html#available()"><tt>available</tt></a> */"/> <method name="public QSemaphore()" doc="/** <p>Equivalent to <a href="QSemaphore.html#QSemaphore(int)"><tt>QSemaphore</tt></a>(0). */"/> <method name="public final void acquire(int n)" doc="/** <p>Tries to acquire <tt>n</tt> resources guarded by the semaphore. If <tt>n</tt> &gt; <a href="QSemaphore.html#available()"><tt>available</tt></a>, this call will block until enough resources are available.</p> @see <a href="QSemaphore.html#release(int)"><tt>release</tt></a> @see <a href="QSemaphore.html#available()"><tt>available</tt></a> @see <a href="QSemaphore.html#tryAcquire(int, int)"><tt>tryAcquire</tt></a> */"/> <method name="public final void acquire()" doc="/** <p>Equivalent to <a href="QSemaphore.html#acquire(int)">acquire</tt></a>(1). */"/> <method name="public final int available()" doc="/** <p>Returns the number of resources currently available to the semaphore. This number can never be negative.</p> @see <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a> @see <a href="QSemaphore.html#release(int)"><tt>release</tt></a> */"/> <method name="public final void release(int n)" doc="/** <p>Releases <tt>n</tt> resources guarded by the semaphore.</p> <p>This function can be used to &quot;create&quot; resources as well. For example:</p> <pre> QSemaphore sem(5); <span class="comment">// a semaphore that guards 5 resources</span> sem.acquire(5); <span class="comment">// acquire all 5 resources</span> sem.release(5); <span class="comment">// release the 5 resources</span> sem.release(10); <span class="comment">// &quot;create&quot; 10 new resources</span></pre> @see <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a> @see <a href="QSemaphore.html#available()"><tt>available</tt></a> */"/> <method name="public final void release()" doc="/** <p>Equivalent to <a href="QSemaphore.html#release(int)">release</tt></a>(1). */"/> <method name="public final boolean tryAcquire(int n)" doc="/** <p>Tries to acquire <tt>n</tt> resources guarded by the semaphore and returns true on success. If <a href="QSemaphore.html#available()"><tt>available</tt></a> &lt; <tt>n</tt>, this call immediately returns false without acquiring any resources.</p> <p>Example:</p> <pre> QSemaphore sem(5); <span class="comment">// sem.available() == 5</span> sem.tryAcquire(250); <span class="comment">// sem.available() == 5, returns false</span> sem.tryAcquire(3); <span class="comment">// sem.available() == 2, returns true</span></pre> @see <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a> */"/> <method name="public final boolean tryAcquire()" doc="/** <p>Equivalent to <a href="QSemaphore.html#tryAcquire(int, int)"><tt>tryAcquire</tt></a>(1). */"/> <method name="public final boolean tryAcquire(int n, int timeout)" doc="/** <p>Tries to acquire <tt>n</tt> resources guarded by the semaphore and returns true on success. If <a href="QSemaphore.html#available()"><tt>available</tt></a> &lt; <tt>n</tt>, this call will wait for at most <tt>timeout</tt> milliseconds for resources to become available.</p> <p>Note: Passing a negative number as the <tt>timeout</tt> is equivalent to calling <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a>, i.e&#x2e; this function will wait forever for resources to become available if <tt>timeout</tt> is negative.</p> <p>Example:</p> <pre> QSemaphore sem(5); <span class="comment">// sem.available() == 5</span> sem.tryAcquire(250, 1000); <span class="comment">// sem.available() == 5, waits 1000 milliseconds and returns false</span> sem.tryAcquire(3, 30000); <span class="comment">// sem.available() == 2, returns true without waiting</span></pre> @see <a href="QSemaphore.html#acquire(int)"><tt>acquire</tt></a> */"/> </class>