← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjlib/include/pj/lock.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjlib/include/pj/lock.h
 
1
/* $Id: lock.h 4359 2013-02-21 11:18:36Z bennylp $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
 
5
 *
 
6
 * This program is free software; you can redistribute it and/or modify
 
7
 * it under the terms of the GNU General Public License as published by
 
8
 * the Free Software Foundation; either version 2 of the License, or
 
9
 * (at your option) any later version.
 
10
 *
 
11
 * This program is distributed in the hope that it will be useful,
 
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
14
 * GNU General Public License for more details.
 
15
 *
 
16
 * You should have received a copy of the GNU General Public License
 
17
 * along with this program; if not, write to the Free Software
 
18
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 
19
 */
 
20
#ifndef __PJ_LOCK_H__
 
21
#define __PJ_LOCK_H__
 
22
 
 
23
/**
 
24
 * @file lock.h
 
25
 * @brief Higher abstraction for locking objects.
 
26
 */
 
27
#include <pj/types.h>
 
28
 
 
29
PJ_BEGIN_DECL
 
30
 
 
31
/**
 
32
 * @defgroup PJ_LOCK Lock Objects
 
33
 * @ingroup PJ_OS
 
34
 * @{
 
35
 *
 
36
 * <b>Lock Objects</b> are higher abstraction for different lock mechanisms.
 
37
 * It offers the same API for manipulating different lock types (e.g.
 
38
 * @ref PJ_MUTEX "mutex", @ref PJ_SEM "semaphores", or null locks).
 
39
 * Because Lock Objects have the same API for different types of lock
 
40
 * implementation, it can be passed around in function arguments. As the
 
41
 * result, it can be used to control locking policy for  a particular
 
42
 * feature.
 
43
 */
 
44
 
 
45
 
 
46
/**
 
47
 * Create simple, non recursive mutex lock object.
 
48
 *
 
49
 * @param pool      Memory pool.
 
50
 * @param name      Lock object's name.
 
51
 * @param lock      Pointer to store the returned handle.
 
52
 *
 
53
 * @return          PJ_SUCCESS or the appropriate error code.
 
54
 */
 
55
PJ_DECL(pj_status_t) pj_lock_create_simple_mutex( pj_pool_t *pool,
 
56
                                                  const char *name,
 
57
                                                  pj_lock_t **lock );
 
58
 
 
59
/**
 
60
 * Create recursive mutex lock object.
 
61
 *
 
62
 * @param pool      Memory pool.
 
63
 * @param name      Lock object's name.
 
64
 * @param lock      Pointer to store the returned handle.
 
65
 *
 
66
 * @return          PJ_SUCCESS or the appropriate error code.
 
67
 */
 
68
PJ_DECL(pj_status_t) pj_lock_create_recursive_mutex( pj_pool_t *pool,
 
69
                                                     const char *name,
 
70
                                                     pj_lock_t **lock );
 
71
 
 
72
 
 
73
/**
 
74
 * Create NULL mutex. A NULL mutex doesn't actually have any synchronization
 
75
 * object attached to it.
 
76
 *
 
77
 * @param pool      Memory pool.
 
78
 * @param name      Lock object's name.
 
79
 * @param lock      Pointer to store the returned handle.
 
80
 *
 
81
 * @return          PJ_SUCCESS or the appropriate error code.
 
82
 */
 
83
PJ_DECL(pj_status_t) pj_lock_create_null_mutex( pj_pool_t *pool,
 
84
                                                const char *name,
 
85
                                                pj_lock_t **lock );
 
86
 
 
87
 
 
88
#if defined(PJ_HAS_SEMAPHORE) && PJ_HAS_SEMAPHORE != 0
 
89
/**
 
90
 * Create semaphore lock object.
 
91
 *
 
92
 * @param pool      Memory pool.
 
93
 * @param name      Lock object's name.
 
94
 * @param initial   Initial value of the semaphore.
 
95
 * @param max       Maximum value of the semaphore.
 
96
 * @param lock      Pointer to store the returned handle.
 
97
 *
 
98
 * @return          PJ_SUCCESS or the appropriate error code.
 
99
 */
 
100
PJ_DECL(pj_status_t) pj_lock_create_semaphore( pj_pool_t *pool,
 
101
                                               const char *name,
 
102
                                               unsigned initial,
 
103
                                               unsigned max,
 
104
                                               pj_lock_t **lock );
 
105
 
 
106
#endif  /* PJ_HAS_SEMAPHORE */
 
107
 
 
108
/**
 
109
 * Acquire lock on the specified lock object.
 
110
 *
 
111
 * @param lock      The lock object.
 
112
 *
 
113
 * @return          PJ_SUCCESS or the appropriate error code.
 
114
 */
 
115
PJ_DECL(pj_status_t) pj_lock_acquire( pj_lock_t *lock );
 
116
 
 
117
 
 
118
/**
 
119
 * Try to acquire lock on the specified lock object.
 
120
 *
 
121
 * @param lock      The lock object.
 
122
 *
 
123
 * @return          PJ_SUCCESS or the appropriate error code.
 
124
 */
 
125
PJ_DECL(pj_status_t) pj_lock_tryacquire( pj_lock_t *lock );
 
126
 
 
127
 
 
128
/**
 
129
 * Release lock on the specified lock object.
 
130
 *
 
131
 * @param lock      The lock object.
 
132
 *
 
133
 * @return          PJ_SUCCESS or the appropriate error code.
 
134
 */
 
135
PJ_DECL(pj_status_t) pj_lock_release( pj_lock_t *lock );
 
136
 
 
137
 
 
138
/**
 
139
 * Destroy the lock object.
 
140
 *
 
141
 * @param lock      The lock object.
 
142
 *
 
143
 * @return          PJ_SUCCESS or the appropriate error code.
 
144
 */
 
145
PJ_DECL(pj_status_t) pj_lock_destroy( pj_lock_t *lock );
 
146
 
 
147
 
 
148
/** @} */
 
149
 
 
150
 
 
151
/**
 
152
 * @defgroup PJ_GRP_LOCK Group Lock
 
153
 * @ingroup PJ_LOCK
 
154
 * @{
 
155
 *
 
156
 * Group lock is a synchronization object to manage concurrency among members
 
157
 * within the same logical group. Example of such groups are:
 
158
 *
 
159
 *   - dialog, which has members such as the dialog itself, an invite session,
 
160
 *     and several transactions
 
161
 *   - ICE, which has members such as ICE stream transport, ICE session, STUN
 
162
 *     socket, TURN socket, and down to ioqueue key
 
163
 *
 
164
 * Group lock has three functions:
 
165
 *
 
166
 *   - mutual exclusion: to protect resources from being accessed by more than
 
167
 *     one threads at the same time
 
168
 *   - session management: to make sure that the resource is not destroyed
 
169
 *     while others are still using or about to use it.
 
170
 *   - lock coordinator: to provide uniform lock ordering among more than one
 
171
 *     lock objects, which is necessary to avoid deadlock.
 
172
 *
 
173
 * The requirements of the group lock are:
 
174
 *
 
175
 *    - must satisfy all the functions above
 
176
 *    - must allow members to join or leave the group (for example,
 
177
 *      transaction may be added or removed from a dialog)
 
178
 *    - must be able to synchronize with external lock (for example, a dialog
 
179
 *      lock must be able to sync itself with PJSUA lock)
 
180
 *
 
181
 * Please see https://trac.pjsip.org/repos/wiki/Group_Lock for more info.
 
182
 */
 
183
 
 
184
/**
 
185
 * Settings for creating the group lock.
 
186
 */
 
187
typedef struct pj_grp_lock_config
 
188
{
 
189
    /**
 
190
     * Creation flags, currently must be zero.
 
191
     */
 
192
    unsigned    flags;
 
193
 
 
194
} pj_grp_lock_config;
 
195
 
 
196
 
 
197
/**
 
198
 * Initialize the config with the default values.
 
199
 *
 
200
 * @param cfg           The config to be initialized.
 
201
 */
 
202
PJ_DECL(void) pj_grp_lock_config_default(pj_grp_lock_config *cfg);
 
203
 
 
204
/**
 
205
 * Create a group lock object. Initially the group lock will have reference
 
206
 * counter of one.
 
207
 *
 
208
 * @param pool          The group lock only uses the pool parameter to get
 
209
 *                      the pool factory, from which it will create its own
 
210
 *                      pool.
 
211
 * @param cfg           Optional configuration.
 
212
 * @param p_grp_lock    Pointer to receive the newly created group lock.
 
213
 *
 
214
 * @return              PJ_SUCCESS or the appropriate error code.
 
215
 */
 
216
PJ_DECL(pj_status_t) pj_grp_lock_create(pj_pool_t *pool,
 
217
                                        const pj_grp_lock_config *cfg,
 
218
                                        pj_grp_lock_t **p_grp_lock);
 
219
 
 
220
/**
 
221
 * Forcibly destroy the group lock, ignoring the reference counter value.
 
222
 *
 
223
 * @param grp_lock      The group lock.
 
224
 *
 
225
 * @return              PJ_SUCCESS or the appropriate error code.
 
226
 */
 
227
PJ_DECL(pj_status_t) pj_grp_lock_destroy( pj_grp_lock_t *grp_lock);
 
228
 
 
229
/**
 
230
 * Move the contents of the old lock to the new lock and destroy the
 
231
 * old lock.
 
232
 *
 
233
 * @param old_lock      The old group lock to be destroyed.
 
234
 * @param new_lock      The new group lock.
 
235
 *
 
236
 * @return              PJ_SUCCESS or the appropriate error code.
 
237
 */
 
238
PJ_DECL(pj_status_t) pj_grp_lock_replace(pj_grp_lock_t *old_lock,
 
239
                                         pj_grp_lock_t *new_lock);
 
240
 
 
241
/**
 
242
 * Acquire lock on the specified group lock.
 
243
 *
 
244
 * @param grp_lock      The group lock.
 
245
 *
 
246
 * @return              PJ_SUCCESS or the appropriate error code.
 
247
 */
 
248
PJ_DECL(pj_status_t) pj_grp_lock_acquire( pj_grp_lock_t *grp_lock);
 
249
 
 
250
/**
 
251
 * Acquire lock on the specified group lock if it is available, otherwise
 
252
 * return immediately wihout waiting.
 
253
 *
 
254
 * @param grp_lock      The group lock.
 
255
 *
 
256
 * @return              PJ_SUCCESS or the appropriate error code.
 
257
 */
 
258
PJ_DECL(pj_status_t) pj_grp_lock_tryacquire( pj_grp_lock_t *grp_lock);
 
259
 
 
260
/**
 
261
 * Release the previously held lock. This may cause the group lock
 
262
 * to be destroyed if it is the last one to hold the reference counter.
 
263
 * In that case, the function will return PJ_EGONE.
 
264
 *
 
265
 * @param grp_lock      The group lock.
 
266
 *
 
267
 * @return              PJ_SUCCESS or the appropriate error code.
 
268
 */
 
269
PJ_DECL(pj_status_t) pj_grp_lock_release( pj_grp_lock_t *grp_lock);
 
270
 
 
271
/**
 
272
 * Add a destructor handler, to be called by the group lock when it is
 
273
 * about to be destroyed.
 
274
 *
 
275
 * @param grp_lock      The group lock.
 
276
 * @param pool          Pool to allocate memory for the handler.
 
277
 * @param member        A pointer to be passed to the handler.
 
278
 * @param handler       The destroy handler.
 
279
 *
 
280
 * @return              PJ_SUCCESS or the appropriate error code.
 
281
 */
 
282
PJ_DECL(pj_status_t) pj_grp_lock_add_handler(pj_grp_lock_t *grp_lock,
 
283
                                             pj_pool_t *pool,
 
284
                                             void *member,
 
285
                                             void (*handler)(void *member));
 
286
 
 
287
/**
 
288
 * Remove previously registered handler. All parameters must be the same
 
289
 * as when the handler was added.
 
290
 *
 
291
 * @param grp_lock      The group lock.
 
292
 * @param member        A pointer to be passed to the handler.
 
293
 * @param handler       The destroy handler.
 
294
 *
 
295
 * @return              PJ_SUCCESS or the appropriate error code.
 
296
 */
 
297
PJ_DECL(pj_status_t) pj_grp_lock_del_handler(pj_grp_lock_t *grp_lock,
 
298
                                             void *member,
 
299
                                             void (*handler)(void *member));
 
300
 
 
301
/**
 
302
 * Increment reference counter to prevent the group lock grom being destroyed.
 
303
 *
 
304
 * @param grp_lock      The group lock.
 
305
 *
 
306
 * @return              PJ_SUCCESS or the appropriate error code.
 
307
 */
 
308
#if !PJ_GRP_LOCK_DEBUG
 
309
PJ_DECL(pj_status_t) pj_grp_lock_add_ref(pj_grp_lock_t *grp_lock);
 
310
 
 
311
#define pj_grp_lock_add_ref_dbg(grp_lock, x, y) pj_grp_lock_add_ref(grp_lock)
 
312
 
 
313
#else
 
314
 
 
315
#define pj_grp_lock_add_ref(g)  pj_grp_lock_add_ref_dbg(g, __FILE__, __LINE__)
 
316
 
 
317
PJ_DECL(pj_status_t) pj_grp_lock_add_ref_dbg(pj_grp_lock_t *grp_lock,
 
318
                                             const char *file,
 
319
                                             int line);
 
320
#endif
 
321
 
 
322
/**
 
323
 * Decrement the reference counter. When the counter value reaches zero, the
 
324
 * group lock will be destroyed and all destructor handlers will be called.
 
325
 *
 
326
 * @param grp_lock      The group lock.
 
327
 *
 
328
 * @return              PJ_SUCCESS or the appropriate error code.
 
329
 */
 
330
#if !PJ_GRP_LOCK_DEBUG
 
331
PJ_DECL(pj_status_t) pj_grp_lock_dec_ref(pj_grp_lock_t *grp_lock);
 
332
 
 
333
#define pj_grp_lock_dec_ref_dbg(grp_lock, x, y) pj_grp_lock_dec_ref(grp_lock)
 
334
#else
 
335
 
 
336
#define pj_grp_lock_dec_ref(g)  pj_grp_lock_dec_ref_dbg(g, __FILE__, __LINE__)
 
337
 
 
338
PJ_DECL(pj_status_t) pj_grp_lock_dec_ref_dbg(pj_grp_lock_t *grp_lock,
 
339
                                             const char *file,
 
340
                                             int line);
 
341
 
 
342
#endif
 
343
 
 
344
/**
 
345
 * Get current reference count value. This normally is only used for
 
346
 * debugging purpose.
 
347
 *
 
348
 * @param grp_lock      The group lock.
 
349
 *
 
350
 * @return              The reference count value.
 
351
 */
 
352
PJ_DECL(int) pj_grp_lock_get_ref(pj_grp_lock_t *grp_lock);
 
353
 
 
354
 
 
355
/**
 
356
 * Dump group lock info for debugging purpose. If group lock debugging is
 
357
 * enabled (via PJ_GRP_LOCK_DEBUG) macro, this will print the group lock
 
358
 * reference counter value along with the source file and line. If
 
359
 * debugging is disabled, this will only print the reference counter.
 
360
 *
 
361
 * @param grp_lock      The group lock.
 
362
 */
 
363
PJ_DECL(void) pj_grp_lock_dump(pj_grp_lock_t *grp_lock);
 
364
 
 
365
 
 
366
/**
 
367
 * Synchronize an external lock with the group lock, by adding it to the
 
368
 * list of locks to be acquired by the group lock when the group lock is
 
369
 * acquired.
 
370
 *
 
371
 * The ''pos'' argument specifies the lock order and also the relative
 
372
 * position with regard to lock ordering against the group lock. Locks with
 
373
 * lower ''pos'' value will be locked first, and those with negative value
 
374
 * will be locked before the group lock (the group lock's ''pos'' value is
 
375
 * zero).
 
376
 *
 
377
 * @param grp_lock      The group lock.
 
378
 * @param ext_lock      The external lock
 
379
 * @param pos           The position.
 
380
 *
 
381
 * @return              PJ_SUCCESS or the appropriate error code.
 
382
 */
 
383
PJ_DECL(pj_status_t) pj_grp_lock_chain_lock(pj_grp_lock_t *grp_lock,
 
384
                                            pj_lock_t *ext_lock,
 
385
                                            int pos);
 
386
 
 
387
/**
 
388
 * Remove an external lock from group lock's list of synchronized locks.
 
389
 *
 
390
 * @param grp_lock      The group lock.
 
391
 * @param ext_lock      The external lock
 
392
 *
 
393
 * @return              PJ_SUCCESS or the appropriate error code.
 
394
 */
 
395
PJ_DECL(pj_status_t) pj_grp_lock_unchain_lock(pj_grp_lock_t *grp_lock,
 
396
                                              pj_lock_t *ext_lock);
 
397
 
 
398
 
 
399
/** @} */
 
400
 
 
401
 
 
402
PJ_END_DECL
 
403
 
 
404
 
 
405
#endif  /* __PJ_LOCK_H__ */
 
406