1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.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 the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qsystemsemaphore.h"
#include "qsystemsemaphore_p.h"
#include <qglobal.h>
QT_BEGIN_NAMESPACE
#ifndef QT_NO_SYSTEMSEMAPHORE
/*!
\class QSystemSemaphore
\ingroup ipc
\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 doc/src/snippets/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:
\bold{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.
\bold{Unix:}
\list
\o 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.
\o 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.
\o Symbian: QSystemSemaphore behaves the same as Windows semaphores.
In other words, the operating system owns the semaphore and ignores
QSystemSemaphore::AccessMode.
\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 and in Symbian, \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 and in Symbian, 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 and in Symbian, 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->error = NoError;
d->errorString = QString();
#if !defined(Q_OS_WIN) && !defined(Q_OS_SYMBIAN)
// 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 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 true
unless there is a system error.
Example: Create a system semaphore having five resources; acquire
them all and then release them all.
\snippet doc/src/snippets/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 doc/src/snippets/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
|