updated Doxyfile
[strongswan.git] / src / libstrongswan / utils / mutex.h
1 /*
2 * Copyright (C) 2008 Tobias Brunner
3 * Copyright (C) 2008 Martin Willi
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 *
16 * $Id$
17 */
18
19 /**
20 * @defgroup mutex mutex
21 * @{ @ingroup utils
22 */
23
24 #ifndef MUTEX_H_
25 #define MUTEX_H_
26
27 typedef struct mutex_t mutex_t;
28 typedef struct condvar_t condvar_t;
29 typedef struct rwlock_t rwlock_t;
30 typedef enum mutex_type_t mutex_type_t;
31 typedef enum condvar_type_t condvar_type_t;
32 typedef enum rwlock_type_t rwlock_type_t;
33
34 #include <library.h>
35
36 /**
37 * Type of mutex.
38 */
39 enum mutex_type_t {
40 /** default mutex */
41 MUTEX_DEFAULT = 0,
42 /** allow recursive locking of the mutex */
43 MUTEX_RECURSIVE = 1,
44 };
45
46 /**
47 * Type of condvar.
48 */
49 enum condvar_type_t {
50 /** default condvar */
51 CONDVAR_DEFAULT = 0,
52 };
53
54 /**
55 * Type of read-write lock.
56 */
57 enum rwlock_type_t {
58 /** default condvar */
59 RWLOCK_DEFAULT = 0,
60 };
61
62 /**
63 * Mutex wrapper implements simple, portable and advanced mutex functions.
64 */
65 struct mutex_t {
66
67 /**
68 * Acquire the lock to the mutex.
69 */
70 void (*lock)(mutex_t *this);
71
72 /**
73 * Release the lock on the mutex.
74 */
75 void (*unlock)(mutex_t *this);
76
77 /**
78 * Destroy a mutex instance.
79 */
80 void (*destroy)(mutex_t *this);
81 };
82
83 /**
84 * Condvar wrapper to use in conjunction with mutex_t.
85 */
86 struct condvar_t {
87
88 /**
89 * Wait on a condvar until it gets signalized.
90 *
91 * @param mutex mutex to release while waiting
92 */
93 void (*wait)(condvar_t *this, mutex_t *mutex);
94
95 /**
96 * Wait on a condvar until it gets signalized, or times out.
97 *
98 * @param mutex mutex to release while waiting
99 * @param timeout timeout im ms
100 * @return TRUE if timed out, FALSE otherwise
101 */
102 bool (*timed_wait)(condvar_t *this, mutex_t *mutex, u_int timeout);
103
104 /**
105 * Wait on a condvar until it gets signalized, or times out.
106 *
107 * @param mutex mutex to release while waiting
108 * @param time absolute time until timeout
109 * @return TRUE if timed out, FALSE otherwise
110 */
111 bool (*timed_wait_abs)(condvar_t *this, mutex_t *mutex, timeval_t timeout);
112
113 /**
114 * Wake up a single thread in a condvar.
115 */
116 void (*signal)(condvar_t *this);
117
118 /**
119 * Wake up all threads in a condvar.
120 */
121 void (*broadcast)(condvar_t *this);
122
123 /**
124 * Destroy a condvar and free its resources.
125 */
126 void (*destroy)(condvar_t *this);
127 };
128
129 /**
130 * Read-Write lock wrapper.
131 */
132 struct rwlock_t {
133
134 /**
135 * Acquire the read lock.
136 */
137 void (*read_lock)(rwlock_t *this);
138
139 /**
140 * Acquire the write lock.
141 */
142 void (*write_lock)(rwlock_t *this);
143
144 /**
145 * Try to acquire the write lock.
146 *
147 * Never blocks, but returns FALSE if the lock was already occupied.
148 *
149 * @return TRUE if lock acquired
150 */
151 bool (*try_write_lock)(rwlock_t *this);
152
153 /**
154 * Release any acquired lock.
155 */
156 void (*unlock)(rwlock_t *this);
157
158 /**
159 * Destroy the read-write lock.
160 */
161 void (*destroy)(rwlock_t *this);
162 };
163
164 /**
165 * Create a mutex instance.
166 *
167 * @param type type of mutex to create
168 * @return unlocked mutex instance
169 */
170 mutex_t *mutex_create(mutex_type_t type);
171
172 /**
173 * Create a condvar instance.
174 *
175 * @param type type of condvar to create
176 * @return condvar instance
177 */
178 condvar_t *condvar_create(condvar_type_t type);
179
180 /**
181 * Create a read-write lock instance.
182 *
183 * @param type type of rwlock to create
184 * @return unlocked rwlock instance
185 */
186 rwlock_t *rwlock_create(rwlock_type_t type);
187
188 #endif /** MUTEX_H_ @}*/