1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-threads.h D-Bus threads handling
3 *
4 * Copyright (C) 2002, 2003, 2006 Red Hat Inc.
5 *
6 * Licensed under the Academic Free License version 2.1
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 *
22 */
23 #include <config.h>
24 #include "dbus-threads.h"
25 #include "dbus-internals.h"
26 #include "dbus-threads-internal.h"
27 #include "dbus-list.h"
28
29 static int thread_init_generation = 0;
30
31 /**
32 * @defgroup DBusThreadsInternals Thread functions
33 * @ingroup DBusInternals
34 * @brief _dbus_rmutex_lock(), etc.
35 *
36 * Functions and macros related to threads and thread locks.
37 *
38 * @{
39 */
40
41 /**
42 * Creates a new mutex
43 * or creates a no-op mutex if threads are not initialized.
44 * May return #NULL even if threads are initialized, indicating
45 * out-of-memory.
46 *
47 * If possible, the mutex returned by this function is recursive, to
48 * avoid deadlocks. However, that cannot be relied on.
49 *
50 * @param location_p the location of the new mutex, can return #NULL on OOM
51 */
52 void
_dbus_rmutex_new_at_location(DBusRMutex ** location_p)53 _dbus_rmutex_new_at_location (DBusRMutex **location_p)
54 {
55 _dbus_assert (location_p != NULL);
56
57 if (!dbus_threads_init_default ())
58 {
59 *location_p = NULL;
60 return;
61 }
62
63 *location_p = _dbus_platform_rmutex_new ();
64 }
65
66 /**
67 * Creates a new mutex
68 * or creates a no-op mutex if threads are not initialized.
69 * May return #NULL even if threads are initialized, indicating
70 * out-of-memory.
71 *
72 * The returned mutex is suitable for use with condition variables.
73 *
74 * @param location_p the location of the new mutex, can return #NULL on OOM
75 */
76 void
_dbus_cmutex_new_at_location(DBusCMutex ** location_p)77 _dbus_cmutex_new_at_location (DBusCMutex **location_p)
78 {
79 _dbus_assert (location_p != NULL);
80
81 if (!dbus_threads_init_default ())
82 {
83 *location_p = NULL;
84 return;
85 }
86
87 *location_p = _dbus_platform_cmutex_new ();
88 }
89
90 /**
91 * Frees a DBusRMutex; does nothing if passed a #NULL pointer.
92 */
93 void
_dbus_rmutex_free_at_location(DBusRMutex ** location_p)94 _dbus_rmutex_free_at_location (DBusRMutex **location_p)
95 {
96 if (location_p == NULL)
97 return;
98
99 if (*location_p != NULL)
100 _dbus_platform_rmutex_free (*location_p);
101 }
102
103 /**
104 * Frees a DBusCMutex; does nothing if passed a #NULL pointer.
105 */
106 void
_dbus_cmutex_free_at_location(DBusCMutex ** location_p)107 _dbus_cmutex_free_at_location (DBusCMutex **location_p)
108 {
109 if (location_p == NULL)
110 return;
111
112 if (*location_p != NULL)
113 _dbus_platform_cmutex_free (*location_p);
114 }
115
116 /**
117 * Locks a mutex. Does nothing if passed a #NULL pointer.
118 * Locks may be recursive if threading implementation initialized
119 * recursive locks.
120 */
121 void
_dbus_rmutex_lock(DBusRMutex * mutex)122 _dbus_rmutex_lock (DBusRMutex *mutex)
123 {
124 if (mutex == NULL)
125 return;
126
127 _dbus_platform_rmutex_lock (mutex);
128 }
129
130 /**
131 * Locks a mutex. Does nothing if passed a #NULL pointer.
132 * Locks may be recursive if threading implementation initialized
133 * recursive locks.
134 */
135 void
_dbus_cmutex_lock(DBusCMutex * mutex)136 _dbus_cmutex_lock (DBusCMutex *mutex)
137 {
138 if (mutex == NULL)
139 return;
140
141 _dbus_platform_cmutex_lock (mutex);
142 }
143
144 /**
145 * Unlocks a mutex. Does nothing if passed a #NULL pointer.
146 *
147 * @returns #TRUE on success
148 */
149 void
_dbus_rmutex_unlock(DBusRMutex * mutex)150 _dbus_rmutex_unlock (DBusRMutex *mutex)
151 {
152 if (mutex == NULL)
153 return;
154
155 _dbus_platform_rmutex_unlock (mutex);
156 }
157
158 /**
159 * Unlocks a mutex. Does nothing if passed a #NULL pointer.
160 *
161 * @returns #TRUE on success
162 */
163 void
_dbus_cmutex_unlock(DBusCMutex * mutex)164 _dbus_cmutex_unlock (DBusCMutex *mutex)
165 {
166 if (mutex == NULL)
167 return;
168
169 _dbus_platform_cmutex_unlock (mutex);
170 }
171
172 /**
173 * Creates a new condition variable using the function supplied
174 * to dbus_threads_init(), or creates a no-op condition variable
175 * if threads are not initialized. May return #NULL even if
176 * threads are initialized, indicating out-of-memory.
177 *
178 * @returns new mutex or #NULL
179 */
180 DBusCondVar *
_dbus_condvar_new(void)181 _dbus_condvar_new (void)
182 {
183 if (!dbus_threads_init_default ())
184 return NULL;
185
186 return _dbus_platform_condvar_new ();
187 }
188
189
190 /**
191 * This does the same thing as _dbus_condvar_new. It however
192 * gives another level of indirection by allocating a pointer
193 * to point to the condvar location; this used to be useful.
194 *
195 * @returns the location of a new condvar or #NULL on OOM
196 */
197
198 void
_dbus_condvar_new_at_location(DBusCondVar ** location_p)199 _dbus_condvar_new_at_location (DBusCondVar **location_p)
200 {
201 _dbus_assert (location_p != NULL);
202
203 *location_p = _dbus_condvar_new();
204 }
205
206
207 /**
208 * Frees a conditional variable created with dbus_condvar_new(); does
209 * nothing if passed a #NULL pointer.
210 */
211 void
_dbus_condvar_free(DBusCondVar * cond)212 _dbus_condvar_free (DBusCondVar *cond)
213 {
214 if (cond == NULL)
215 return;
216
217 _dbus_platform_condvar_free (cond);
218 }
219
220 /**
221 * Frees a condition variable; does nothing if passed a #NULL pointer.
222 */
223 void
_dbus_condvar_free_at_location(DBusCondVar ** location_p)224 _dbus_condvar_free_at_location (DBusCondVar **location_p)
225 {
226 if (location_p == NULL)
227 return;
228
229 if (*location_p != NULL)
230 _dbus_platform_condvar_free (*location_p);
231 }
232
233 /**
234 * Atomically unlocks the mutex and waits for the conditions
235 * variable to be signalled. Locks the mutex again before
236 * returning.
237 * Does nothing if passed a #NULL pointer.
238 */
239 void
_dbus_condvar_wait(DBusCondVar * cond,DBusCMutex * mutex)240 _dbus_condvar_wait (DBusCondVar *cond,
241 DBusCMutex *mutex)
242 {
243 if (cond == NULL || mutex == NULL)
244 return;
245
246 _dbus_platform_condvar_wait (cond, mutex);
247 }
248
249 /**
250 * Atomically unlocks the mutex and waits for the conditions variable
251 * to be signalled, or for a timeout. Locks the mutex again before
252 * returning. Does nothing if passed a #NULL pointer. Return value
253 * is #FALSE if we timed out, #TRUE otherwise.
254 *
255 * @param cond the condition variable
256 * @param mutex the mutex
257 * @param timeout_milliseconds the maximum time to wait
258 * @returns #FALSE if the timeout occurred, #TRUE if not
259 */
260 dbus_bool_t
_dbus_condvar_wait_timeout(DBusCondVar * cond,DBusCMutex * mutex,int timeout_milliseconds)261 _dbus_condvar_wait_timeout (DBusCondVar *cond,
262 DBusCMutex *mutex,
263 int timeout_milliseconds)
264 {
265 if (cond == NULL || mutex == NULL)
266 return TRUE;
267
268 return _dbus_platform_condvar_wait_timeout (cond, mutex,
269 timeout_milliseconds);
270 }
271
272 /**
273 * If there are threads waiting on the condition variable, wake
274 * up exactly one.
275 * Does nothing if passed a #NULL pointer.
276 */
277 void
_dbus_condvar_wake_one(DBusCondVar * cond)278 _dbus_condvar_wake_one (DBusCondVar *cond)
279 {
280 if (cond == NULL)
281 return;
282
283 _dbus_platform_condvar_wake_one (cond);
284 }
285
286 static DBusRMutex *global_locks[_DBUS_N_GLOBAL_LOCKS] = { NULL };
287
288 static void
shutdown_global_locks(void * nil)289 shutdown_global_locks (void *nil)
290 {
291 int i;
292
293 for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
294 {
295 _dbus_assert (global_locks[i] != NULL);
296 _dbus_platform_rmutex_free (global_locks[i]);
297 global_locks[i] = NULL;
298 }
299 }
300
301 static dbus_bool_t
init_global_locks(void)302 init_global_locks (void)
303 {
304 int i;
305 dbus_bool_t ok;
306
307 for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
308 {
309 _dbus_assert (global_locks[i] == NULL);
310
311 global_locks[i] = _dbus_platform_rmutex_new ();
312
313 if (global_locks[i] == NULL)
314 goto failed;
315 }
316
317 _dbus_platform_rmutex_lock (global_locks[_DBUS_LOCK_shutdown_funcs]);
318 ok = _dbus_register_shutdown_func_unlocked (shutdown_global_locks, NULL);
319 _dbus_platform_rmutex_unlock (global_locks[_DBUS_LOCK_shutdown_funcs]);
320
321 if (!ok)
322 goto failed;
323
324 return TRUE;
325
326 failed:
327 for (i = i - 1; i >= 0; i--)
328 {
329 _dbus_platform_rmutex_free (global_locks[i]);
330 global_locks[i] = NULL;
331 }
332
333 return FALSE;
334 }
335
336 dbus_bool_t
_dbus_lock(DBusGlobalLock lock)337 _dbus_lock (DBusGlobalLock lock)
338 {
339 _dbus_assert (lock >= 0);
340 _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
341
342 if (thread_init_generation != _dbus_current_generation &&
343 !dbus_threads_init_default ())
344 return FALSE;
345
346 _dbus_platform_rmutex_lock (global_locks[lock]);
347 return TRUE;
348 }
349
350 void
_dbus_unlock(DBusGlobalLock lock)351 _dbus_unlock (DBusGlobalLock lock)
352 {
353 _dbus_assert (lock >= 0);
354 _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
355
356 _dbus_platform_rmutex_unlock (global_locks[lock]);
357 }
358
359 /** @} */ /* end of internals */
360
361 /**
362 * @defgroup DBusThreads Thread functions
363 * @ingroup DBus
364 * @brief dbus_threads_init() and dbus_threads_init_default()
365 *
366 * Functions and macros related to threads and thread locks.
367 *
368 * If threads are initialized, the D-Bus library has locks on all
369 * global data structures. In addition, each #DBusConnection has a
370 * lock, so only one thread at a time can touch the connection. (See
371 * @ref DBusConnection for more on connection locking.)
372 *
373 * Most other objects, however, do not have locks - they can only be
374 * used from a single thread at a time, unless you lock them yourself.
375 * For example, a #DBusMessage can't be modified from two threads
376 * at once.
377 *
378 * @{
379 */
380
381 /**
382 * Initializes threads, like dbus_threads_init_default().
383 * This version previously allowed user-specified threading
384 * primitives, but since D-Bus 1.6 it ignores them and behaves
385 * exactly like dbus_threads_init_default().
386 *
387 * @param functions ignored, formerly functions for using threads
388 * @returns #TRUE on success, #FALSE if no memory
389 */
390 dbus_bool_t
dbus_threads_init(const DBusThreadFunctions * functions)391 dbus_threads_init (const DBusThreadFunctions *functions)
392 {
393 _dbus_threads_lock_platform_specific ();
394
395 if (thread_init_generation == _dbus_current_generation)
396 {
397 _dbus_threads_unlock_platform_specific ();
398 return TRUE;
399 }
400
401 if (!_dbus_threads_init_platform_specific() ||
402 !init_global_locks ())
403 {
404 _dbus_threads_unlock_platform_specific ();
405 return FALSE;
406 }
407
408 thread_init_generation = _dbus_current_generation;
409
410 _dbus_threads_unlock_platform_specific ();
411 return TRUE;
412 }
413
414
415
416 /* Default thread implemenation */
417
418 /**
419 * Initializes threads. If this function is not called, the D-Bus
420 * library will not lock any data structures. If it is called, D-Bus
421 * will do locking, at some cost in efficiency.
422 *
423 * Since D-Bus 1.7 it is safe to call this function from any thread,
424 * any number of times (but it must be called before any other
425 * libdbus API is used).
426 *
427 * In D-Bus 1.6 or older, this function must be called in the main thread
428 * before any other thread starts. As a result, it is not sufficient to
429 * call this function in a library or plugin, unless the library or plugin
430 * imposes a similar requirement on its callers.
431 *
432 * dbus_shutdown() reverses the effects of this function when it
433 * resets all global state in libdbus.
434 *
435 * @returns #TRUE on success, #FALSE if not enough memory
436 */
437 dbus_bool_t
dbus_threads_init_default(void)438 dbus_threads_init_default (void)
439 {
440 return dbus_threads_init (NULL);
441 }
442
443
444 /** @} */
445
446 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
447
448 dbus_bool_t
_dbus_threads_init_debug(void)449 _dbus_threads_init_debug (void)
450 {
451 return dbus_threads_init (NULL);
452 }
453
454 #endif /* DBUS_ENABLE_EMBEDDED_TESTS */
455