diff options
Diffstat (limited to 'src/corelib/kernel/qsystemsemaphore.cpp')
| -rw-r--r-- | src/corelib/kernel/qsystemsemaphore.cpp | 357 |
1 files changed, 0 insertions, 357 deletions
diff --git a/src/corelib/kernel/qsystemsemaphore.cpp b/src/corelib/kernel/qsystemsemaphore.cpp deleted file mode 100644 index 011a673d69..0000000000 --- a/src/corelib/kernel/qsystemsemaphore.cpp +++ /dev/null @@ -1,357 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtCore module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 3 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL3 included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 3 requirements -** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 2.0 or (at your option) the GNU General -** Public license version 3 or any later version approved by the KDE Free -** Qt Foundation. The licenses are as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 -** included in the packaging of this file. Please review the following -** information to ensure the GNU General Public License requirements will -** be met: https://www.gnu.org/licenses/gpl-2.0.html and -** https://www.gnu.org/licenses/gpl-3.0.html. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include "qsystemsemaphore.h" -#include "qsystemsemaphore_p.h" -#include <qglobal.h> - -QT_BEGIN_NAMESPACE - -#ifndef QT_NO_SYSTEMSEMAPHORE - -/*! - \class QSystemSemaphore - \inmodule QtCore - \since 4.4 - - \brief The QSystemSemaphore class provides a general counting system semaphore. - - 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. - - Like its lighter counterpart QSemaphore, a QSystemSemaphore can be - accessed from multiple \l {QThread} {threads}. Unlike QSemaphore, a - QSystemSemaphore can also be accessed from multiple \l {QProcess} - {processes}. 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 QSemaphore. - - Semaphores support two fundamental operations, acquire() and release(): - - acquire() 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. - - release() 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. - - A system semaphore is created with a string key that other processes - can use to use the same semaphore. - - Example: Create a system semaphore - \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 0 - - A typical application of system semaphores is for controlling access - to a circular buffer shared by a producer process and a consumer - processes. - - \section1 Platform-Specific Behavior - - When using this class, be aware of the following platform - differences: - - \b{Windows:} 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. - - \b{Unix:} - - \list - \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 \l {QSystemSemaphore::AccessMode} {access mode} as - \l {QSystemSemaphore::} {Open}, 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 \l {QSystemSemaphore::AccessMode} {access mode} as \l - {QSystemSemaphore::} {Create}, which will force Unix to reset the - resource count in the underlying system semaphore. - - \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. - - \endlist - - \sa QSharedMemory, QSemaphore - */ - -/*! - Requests a system semaphore for the specified \a key. The parameters - \a initialValue and \a mode are used according to the following - rules, which are system dependent. - - In Unix, if the \a mode is \l {QSystemSemaphore::} {Open} and the - system already has a semaphore identified by \a key, that semaphore - is used, and the semaphore's resource count is not changed, i.e., \a - initialValue is ignored. But if the system does not already have a - semaphore identified by \a key, it creates a new semaphore for that - key and sets its resource count to \a initialValue. - - In Unix, if the \a mode is \l {QSystemSemaphore::} {Create} and the - system already has a semaphore identified by \a key, that semaphore - is used, and its resource count is set to \a initialValue. If the - system does not already have a semaphore identified by \a key, it - creates a new semaphore for that key and sets its resource count to - \a initialValue. - - In Windows, \a mode is ignored, and the system always tries to - create a semaphore for the specified \a key. If the system does not - already have a semaphore identified as \a key, it creates the - semaphore and sets its resource count to \a initialValue. But if the - system already has a semaphore identified as \a key it uses that - semaphore and ignores \a initialValue. - - The \l {QSystemSemaphore::AccessMode} {mode} 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 \a key will get the semaphore that survived - the crash, and unless \a mode is \l {QSystemSemaphore::} {Create}, - the resource count will not be reset to \a initialValue but will - retain the initial value it had been given by the crashed process. - - \sa acquire(), key() - */ -QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue, AccessMode mode) - : d(new QSystemSemaphorePrivate) -{ - setKey(key, initialValue, mode); -} - -/*! - The destructor destroys the QSystemSemaphore object, but the - underlying system semaphore is not removed from the system unless - this instance of QSystemSemaphore is the last one existing for that - system semaphore. - - Two important side effects of the destructor depend on the system. - In Windows, if acquire() has been called for this semaphore but not - release(), release() will not be called by the destructor, nor will - the resource be released when the process exits normally. This would - be a program bug which could be the cause of a deadlock in another - process trying to acquire the same resource. In Unix, acquired - resources that are not released before the destructor is called are - automatically released when the process exits. -*/ -QSystemSemaphore::~QSystemSemaphore() -{ - d->cleanHandle(); -} - -/*! - \enum QSystemSemaphore::AccessMode - - This enum is used by the constructor and setKey(). 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, where semaphores can't survive a - crash, this enum has no effect. - - \value Open 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. - - \value Create QSystemSemaphore 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, where a semaphore can't survive a crash, Create and Open - have the same behavior. -*/ - -/*! - This function works the same as the constructor. It reconstructs - this QSystemSemaphore object. If the new \a key 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 \a key. The \a initialValue and - \a mode parameters are as defined for the constructor. - - \sa QSystemSemaphore(), key() - */ -void QSystemSemaphore::setKey(const QString &key, int initialValue, AccessMode mode) -{ - if (key == d->key && mode == Open) - return; - d->clearError(); -#if !defined(Q_OS_WIN) && !defined(QT_POSIX_IPC) - // optimization to not destroy/create the file & semaphore - if (key == d->key && mode == Create && d->createdSemaphore && d->createdFile) { - d->initialValue = initialValue; - d->unix_key = -1; - d->handle(mode); - return; - } -#endif - d->cleanHandle(); - d->key = key; - d->initialValue = initialValue; - // cache the file name so it doesn't have to be generated all the time. - d->fileName = d->makeKeyFileName(); - d->handle(mode); -} - -/*! - Returns the key assigned to this system semaphore. The key is the - name by which the semaphore can be accessed from other processes. - - \sa setKey() - */ -QString QSystemSemaphore::key() const -{ - return d->key; -} - -/*! - Acquires one of the resources guarded by this semaphore, if there is - one available, and returns \c 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. - - If false is returned, a system error has occurred. Call error() - to get a value of QSystemSemaphore::SystemSemaphoreError that - indicates which error occurred. - - \sa release() - */ -bool QSystemSemaphore::acquire() -{ - return d->modifySemaphore(-1); -} - -/*! - Releases \a n resources guarded by the semaphore. Returns \c true - unless there is a system error. - - Example: Create a system semaphore having five resources; acquire - them all and then release them all. - - \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 1 - - This function can also "create" resources. For example, immediately - following the sequence of statements above, suppose we add the - statement: - - \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 2 - - 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. - - \sa acquire() - */ -bool QSystemSemaphore::release(int n) -{ - if (n == 0) - return true; - if (n < 0) { - qWarning("QSystemSemaphore::release: n is negative."); - return false; - } - return d->modifySemaphore(n); -} - -/*! - Returns a value indicating whether an error occurred, and, if so, - which error it was. - - \sa errorString() - */ -QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const -{ - return d->error; -} - -/*! - \enum QSystemSemaphore::SystemSemaphoreError - - \value NoError No error occurred. - - \value PermissionDenied The operation failed because the caller - didn't have the required permissions. - - \value KeyError The operation failed because of an invalid key. - - \value AlreadyExists The operation failed because a system - semaphore with the specified key already existed. - - \value NotFound The operation failed because a system semaphore - with the specified key could not be found. - - \value OutOfResources The operation failed because there was - not enough memory available to fill the request. - - \value UnknownError Something else happened and it was bad. -*/ - -/*! - Returns a text description of the last error that occurred. If - error() returns an \l {QSystemSemaphore::SystemSemaphoreError} {error - value}, call this function to get a text string that describes the - error. - - \sa error() - */ -QString QSystemSemaphore::errorString() const -{ - return d->errorString; -} - -#endif // QT_NO_SYSTEMSEMAPHORE - -QT_END_NAMESPACE |