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
|
/* $Id: lock.h 3553 2011-05-05 06:14:19Z nanang $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJ_LOCK_H__
#define __PJ_LOCK_H__
/**
* @file lock.h
* @brief Higher abstraction for locking objects.
*/
#include <pj/types.h>
PJ_BEGIN_DECL
/**
* @defgroup PJ_LOCK Lock Objects
* @ingroup PJ_OS
* @{
*
* <b>Lock Objects</b> are higher abstraction for different lock mechanisms.
* It offers the same API for manipulating different lock types (e.g.
* @ref PJ_MUTEX "mutex", @ref PJ_SEM "semaphores", or null locks).
* Because Lock Objects have the same API for different types of lock
* implementation, it can be passed around in function arguments. As the
* result, it can be used to control locking policy for a particular
* feature.
*/
/**
* Create simple, non recursive mutex lock object.
*
* @param pool Memory pool.
* @param name Lock object's name.
* @param lock Pointer to store the returned handle.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_create_simple_mutex( pj_pool_t *pool,
const char *name,
pj_lock_t **lock );
/**
* Create recursive mutex lock object.
*
* @param pool Memory pool.
* @param name Lock object's name.
* @param lock Pointer to store the returned handle.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_create_recursive_mutex( pj_pool_t *pool,
const char *name,
pj_lock_t **lock );
/**
* Create NULL mutex. A NULL mutex doesn't actually have any synchronization
* object attached to it.
*
* @param pool Memory pool.
* @param name Lock object's name.
* @param lock Pointer to store the returned handle.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_create_null_mutex( pj_pool_t *pool,
const char *name,
pj_lock_t **lock );
#if defined(PJ_HAS_SEMAPHORE) && PJ_HAS_SEMAPHORE != 0
/**
* Create semaphore lock object.
*
* @param pool Memory pool.
* @param name Lock object's name.
* @param initial Initial value of the semaphore.
* @param max Maximum value of the semaphore.
* @param lock Pointer to store the returned handle.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_create_semaphore( pj_pool_t *pool,
const char *name,
unsigned initial,
unsigned max,
pj_lock_t **lock );
#endif /* PJ_HAS_SEMAPHORE */
/**
* Acquire lock on the specified lock object.
*
* @param lock The lock object.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_acquire( pj_lock_t *lock );
/**
* Try to acquire lock on the specified lock object.
*
* @param lock The lock object.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_tryacquire( pj_lock_t *lock );
/**
* Release lock on the specified lock object.
*
* @param lock The lock object.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_release( pj_lock_t *lock );
/**
* Destroy the lock object.
*
* @param lock The lock object.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pj_lock_destroy( pj_lock_t *lock );
/** @} */
PJ_END_DECL
#endif /* __PJ_LOCK_H__ */
|
