/******************************************************************************** Copyright (C) 1992-2006 Trolltech ASA. All rights reserved.**** This file is part of the QtCore module of the Qt Toolkit.**** This file may be used under the terms of the GNU General Public** License version 2.0 as published by the Free Software Foundation** and appearing in the file LICENSE.GPL included in the packaging of** this file.  Please review the following information to ensure GNU** General Public Licensing requirements will be met:** http://www.trolltech.com/products/qt/opensource.html**** If you are unsure which license is appropriate for your use, please** review the following information:** http://www.trolltech.com/products/qt/licensing.html or contact the** sales department at sales@trolltech.com.**** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.******************************************************************************/#include "qsemaphore.h"#ifndef QT_NO_THREAD#include "qmutex.h"#include "qwaitcondition.h"/*!    \class QSemaphore    \brief The QSemaphore class provides a general counting semaphore.    \threadsafe    \ingroup thread    \ingroup environment    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.    Semaphores support two fundamental operations, acquire() and    release():    \list    \o acquire(\e{n}) tries to acquire \e n resources. If there aren't       that many resources available, the call will block until this       is the case.    \o release(\e{n}) releases \e n resources.    \endlist    There's also a tryAcquire() function that returns immediately if    it cannot acquire the resources, and an available() function that    returns the number of available resources at any time.    Example:    \code        QSemaphore sem(5);      // sem.available() == 5        sem.acquire(3);         // sem.available() == 2        sem.acquire(2);         // sem.available() == 0        sem.release(5);         // sem.available() == 5        sem.release(5);         // sem.available() == 10        sem.tryAcquire(1);      // sem.available() == 9, returns true        sem.tryAcquire(250);    // sem.available() == 9, returns false    \endcode    A typical application of semaphores is for controlling access to    a circular buffer shared by a producer thread and a consumer    thread. The \l{threads/semaphores}{Semaphores} example shows how    to use QSemaphore to solve that problem.    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, available() is decremented. As people leave, the    available() 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).    \sa QMutex, QWaitCondition, QThread, {Semaphores Example}*/class QSemaphorePrivate {public:    inline QSemaphorePrivate(int n) : avail(n) { }    QMutex mutex;    QWaitCondition cond;    int avail;};/*!    Creates a new semaphore and initializes the number of resources    it guards to \a n (by default, 0).    \sa release(), available()*/QSemaphore::QSemaphore(int n){    Q_ASSERT_X(n >= 0, "QSemaphore", "parameter 'n' must be non-negative");    d = new QSemaphorePrivate(n);}/*!    Destroys the semaphore.    \warning Destroying a semaphore that is in use may result in    undefined behavior.*/QSemaphore::~QSemaphore(){ delete d; }/*!    Tries to acquire \c n resources guarded by the semaphore. If \a n    > available(), this call will block until enough resources are    available.    \sa release(), available(), tryAcquire()*/void QSemaphore::acquire(int n){    Q_ASSERT_X(n >= 0, "QSemaphore::acquire", "parameter 'n' must be non-negative");    QMutexLocker locker(&d->mutex);    while (n > d->avail)        d->cond.wait(locker.mutex());    d->avail -= n;}/*!    Releases \a n resources guarded by the semaphore.    This function can be used to "create" resources as well. For    example:    \code        QSemaphore sem(5);      // a semaphore that guards 5 resources        sem.acquire(5);         // acquire all 5 resources        sem.release(5);         // release the 5 resources        sem.release(10);        // "create" 10 new resources    \endcode    \sa acquire(), available()*/void QSemaphore::release(int n){    Q_ASSERT_X(n >= 0, "QSemaphore::release", "parameter 'n' must be non-negative");    QMutexLocker locker(&d->mutex);    d->avail += n;    d->cond.wakeAll();}/*!    Returns the number of resources currently available to the    semaphore. This number can never be negative.    \sa acquire(), release()*/int QSemaphore::available() const{    QMutexLocker locker(&d->mutex);    return d->avail;}/*!    Tries to acquire \c n resources guarded by the semaphore and    returns true on success. If available() < \a n, this call    immediately returns false without acquiring any resources.    Example:    \code        QSemaphore sem(5);      // sem.available() == 5        sem.tryAcquire(250);    // sem.available() == 5, returns false        sem.tryAcquire(3);      // sem.available() == 2, returns true    \endcode    \sa acquire()*/bool QSemaphore::tryAcquire(int n){    Q_ASSERT_X(n >= 0, "QSemaphore::tryAcquire", "parameter 'n' must be non-negative");    QMutexLocker locker(&d->mutex);    if (n > d->avail)        return false;    d->avail -= n;    return true;}#endif // QT_NO_THREAD