1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-threads.h D-Bus threads handling
4 * Copyright (C) 2002, 2003, 2006 Red Hat Inc.
6 * Licensed under the Academic Free License version 2.1
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.
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.
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 #include "dbus-threads.h"
24 #include "dbus-internals.h"
25 #include "dbus-threads-internal.h"
26 #include "dbus-list.h"
28 static DBusThreadFunctions thread_functions =
31 NULL, NULL, NULL, NULL, NULL,
32 NULL, NULL, NULL, NULL, NULL,
33 NULL, NULL, NULL, NULL,
35 NULL, NULL, NULL, NULL
38 static int thread_init_generation = 0;
40 static DBusList *uninitialized_mutex_list = NULL;
41 static DBusList *uninitialized_condvar_list = NULL;
43 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
44 #define _DBUS_DUMMY_MUTEX ((DBusMutex*)0xABCDEF)
46 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
47 #define _DBUS_DUMMY_CONDVAR ((DBusCondVar*)0xABCDEF2)
50 * @defgroup DBusThreadsInternals Thread functions
51 * @ingroup DBusInternals
52 * @brief _dbus_mutex_lock(), etc.
54 * Functions and macros related to threads and thread locks.
60 * Creates a new mutex using the function supplied to dbus_threads_init(),
61 * or creates a no-op mutex if threads are not initialized.
62 * May return #NULL even if threads are initialized, indicating
65 * @returns new mutex or #NULL
68 _dbus_mutex_new (void)
70 if (thread_functions.recursive_mutex_new)
71 return (* thread_functions.recursive_mutex_new) ();
72 else if (thread_functions.mutex_new)
73 return (* thread_functions.mutex_new) ();
75 return _DBUS_DUMMY_MUTEX;
79 * This does the same thing as _dbus_mutex_new. It however
80 * gives another level of indirection by allocating a pointer
81 * to point to the mutex location. This allows the threading
82 * module to swap out dummy mutexes for real a real mutex so libraries
83 * can initialize threads even after the D-Bus API has been used.
85 * @param location_p the location of the new mutex, can return #NULL on OOM
88 _dbus_mutex_new_at_location (DBusMutex **location_p)
90 _dbus_assert (location_p != NULL);
92 *location_p = _dbus_mutex_new();
94 if (thread_init_generation != _dbus_current_generation && *location_p)
96 if (!_dbus_list_append (&uninitialized_mutex_list, location_p))
98 _dbus_mutex_free (*location_p);
105 * Frees a mutex created with dbus_mutex_new(); does
106 * nothing if passed a #NULL pointer.
109 _dbus_mutex_free (DBusMutex *mutex)
113 if (mutex && thread_functions.recursive_mutex_free)
114 (* thread_functions.recursive_mutex_free) (mutex);
115 else if (mutex && thread_functions.mutex_free)
116 (* thread_functions.mutex_free) (mutex);
121 * Frees a mutex and removes it from the
122 * uninitialized_mutex_list;
123 * does nothing if passed a #NULL pointer.
126 _dbus_mutex_free_at_location (DBusMutex **location_p)
130 if (thread_init_generation != _dbus_current_generation)
131 _dbus_list_remove (&uninitialized_mutex_list, location_p);
133 _dbus_mutex_free (*location_p);
138 * Locks a mutex. Does nothing if passed a #NULL pointer.
139 * Locks may be recursive if threading implementation initialized
143 _dbus_mutex_lock (DBusMutex *mutex)
147 if (thread_functions.recursive_mutex_lock)
148 (* thread_functions.recursive_mutex_lock) (mutex);
149 else if (thread_functions.mutex_lock)
150 (* thread_functions.mutex_lock) (mutex);
155 * Unlocks a mutex. Does nothing if passed a #NULL pointer.
157 * @returns #TRUE on success
160 _dbus_mutex_unlock (DBusMutex *mutex)
164 if (thread_functions.recursive_mutex_unlock)
165 (* thread_functions.recursive_mutex_unlock) (mutex);
166 else if (thread_functions.mutex_unlock)
167 (* thread_functions.mutex_unlock) (mutex);
172 * Creates a new condition variable using the function supplied
173 * to dbus_threads_init(), or creates a no-op condition variable
174 * if threads are not initialized. May return #NULL even if
175 * threads are initialized, indicating out-of-memory.
177 * @returns new mutex or #NULL
180 _dbus_condvar_new (void)
182 if (thread_functions.condvar_new)
183 return (* thread_functions.condvar_new) ();
185 return _DBUS_DUMMY_CONDVAR;
190 * This does the same thing as _dbus_condvar_new. It however
191 * gives another level of indirection by allocating a pointer
192 * to point to the condvar location. This allows the threading
193 * module to swap out dummy condvars for real a real condvar so libraries
194 * can initialize threads even after the D-Bus API has been used.
196 * @returns the location of a new condvar or #NULL on OOM
200 _dbus_condvar_new_at_location (DBusCondVar **location_p)
202 *location_p = _dbus_condvar_new();
204 if (thread_init_generation != _dbus_current_generation && *location_p)
206 if (!_dbus_list_append (&uninitialized_condvar_list, location_p))
208 _dbus_condvar_free (*location_p);
216 * Frees a conditional variable created with dbus_condvar_new(); does
217 * nothing if passed a #NULL pointer.
220 _dbus_condvar_free (DBusCondVar *cond)
222 if (cond && thread_functions.condvar_free)
223 (* thread_functions.condvar_free) (cond);
227 * Frees a conditional variable and removes it from the
228 * uninitialized_condvar_list;
229 * does nothing if passed a #NULL pointer.
232 _dbus_condvar_free_at_location (DBusCondVar **location_p)
236 if (thread_init_generation != _dbus_current_generation)
237 _dbus_list_remove (&uninitialized_condvar_list, location_p);
239 _dbus_condvar_free (*location_p);
244 * Atomically unlocks the mutex and waits for the conditions
245 * variable to be signalled. Locks the mutex again before
247 * Does nothing if passed a #NULL pointer.
250 _dbus_condvar_wait (DBusCondVar *cond,
253 if (cond && mutex && thread_functions.condvar_wait)
254 (* thread_functions.condvar_wait) (cond, mutex);
258 * Atomically unlocks the mutex and waits for the conditions variable
259 * to be signalled, or for a timeout. Locks the mutex again before
260 * returning. Does nothing if passed a #NULL pointer. Return value
261 * is #FALSE if we timed out, #TRUE otherwise.
263 * @param cond the condition variable
264 * @param mutex the mutex
265 * @param timeout_milliseconds the maximum time to wait
266 * @returns #FALSE if the timeout occurred, #TRUE if not
269 _dbus_condvar_wait_timeout (DBusCondVar *cond,
271 int timeout_milliseconds)
273 if (cond && mutex && thread_functions.condvar_wait)
274 return (* thread_functions.condvar_wait_timeout) (cond, mutex, timeout_milliseconds);
280 * If there are threads waiting on the condition variable, wake
282 * Does nothing if passed a #NULL pointer.
285 _dbus_condvar_wake_one (DBusCondVar *cond)
287 if (cond && thread_functions.condvar_wake_one)
288 (* thread_functions.condvar_wake_one) (cond);
292 * If there are threads waiting on the condition variable, wake
294 * Does nothing if passed a #NULL pointer.
297 _dbus_condvar_wake_all (DBusCondVar *cond)
299 if (cond && thread_functions.condvar_wake_all)
300 (* thread_functions.condvar_wake_all) (cond);
304 shutdown_global_locks (void *data)
306 DBusMutex ***locks = data;
310 while (i < _DBUS_N_GLOBAL_LOCKS)
312 _dbus_mutex_free (*(locks[i]));
321 shutdown_uninitialized_locks (void *data)
323 _dbus_list_clear (&uninitialized_mutex_list);
324 _dbus_list_clear (&uninitialized_condvar_list);
328 init_uninitialized_locks (void)
332 _dbus_assert (thread_init_generation != _dbus_current_generation);
334 link = uninitialized_mutex_list;
339 mp = (DBusMutex **)link->data;
340 _dbus_assert (*mp == _DBUS_DUMMY_MUTEX);
342 *mp = _dbus_mutex_new ();
346 link = _dbus_list_get_next_link (&uninitialized_mutex_list, link);
349 link = uninitialized_condvar_list;
354 cp = (DBusCondVar **)link->data;
355 _dbus_assert (*cp == _DBUS_DUMMY_CONDVAR);
357 *cp = _dbus_condvar_new ();
361 link = _dbus_list_get_next_link (&uninitialized_condvar_list, link);
364 _dbus_list_clear (&uninitialized_mutex_list);
365 _dbus_list_clear (&uninitialized_condvar_list);
367 if (!_dbus_register_shutdown_func (shutdown_uninitialized_locks,
374 link = uninitialized_condvar_list;
379 cp = (DBusCondVar **)link->data;
381 if (*cp != _DBUS_DUMMY_CONDVAR)
382 _dbus_condvar_free (*cp);
386 *cp = _DBUS_DUMMY_CONDVAR;
388 link = _dbus_list_get_next_link (&uninitialized_condvar_list, link);
392 link = uninitialized_mutex_list;
397 mp = (DBusMutex **)link->data;
399 if (*mp != _DBUS_DUMMY_MUTEX)
400 _dbus_mutex_free (*mp);
404 *mp = _DBUS_DUMMY_MUTEX;
406 link = _dbus_list_get_next_link (&uninitialized_mutex_list, link);
416 DBusMutex ***dynamic_global_locks;
418 DBusMutex **global_locks[] = {
419 #define LOCK_ADDR(name) (& _dbus_lock_##name)
421 LOCK_ADDR (sid_atom_cache),
423 LOCK_ADDR (connection_slots),
424 LOCK_ADDR (pending_call_slots),
425 LOCK_ADDR (server_slots),
426 LOCK_ADDR (message_slots),
429 LOCK_ADDR (bus_datas),
430 LOCK_ADDR (shutdown_funcs),
431 LOCK_ADDR (system_users),
432 LOCK_ADDR (message_cache),
433 LOCK_ADDR (shared_connections),
434 LOCK_ADDR (machine_uuid)
438 _dbus_assert (_DBUS_N_ELEMENTS (global_locks) ==
439 _DBUS_N_GLOBAL_LOCKS);
443 dynamic_global_locks = dbus_new (DBusMutex**, _DBUS_N_GLOBAL_LOCKS);
444 if (dynamic_global_locks == NULL)
447 while (i < _DBUS_N_ELEMENTS (global_locks))
449 *global_locks[i] = _dbus_mutex_new ();
451 if (*global_locks[i] == NULL)
454 dynamic_global_locks[i] = global_locks[i];
459 if (!_dbus_register_shutdown_func (shutdown_global_locks,
460 dynamic_global_locks))
463 if (!init_uninitialized_locks ())
469 dbus_free (dynamic_global_locks);
471 for (i = i - 1; i >= 0; i--)
473 _dbus_mutex_free (*global_locks[i]);
474 *global_locks[i] = NULL;
479 /** @} */ /* end of internals */
482 * @defgroup DBusThreads Thread functions
484 * @brief dbus_threads_init() and dbus_threads_init_default()
486 * Functions and macros related to threads and thread locks.
488 * If threads are initialized, the D-Bus library has locks on all
489 * global data structures. In addition, each #DBusConnection has a
490 * lock, so only one thread at a time can touch the connection. (See
491 * @ref DBusConnection for more on connection locking.)
493 * Most other objects, however, do not have locks - they can only be
494 * used from a single thread at a time, unless you lock them yourself.
495 * For example, a #DBusMessage can't be modified from two threads
503 * Initializes threads. If this function is not called, the D-Bus
504 * library will not lock any data structures. If it is called, D-Bus
505 * will do locking, at some cost in efficiency. Note that this
506 * function must be called BEFORE the second thread is started.
508 * Almost always, you should use dbus_threads_init_default() instead.
509 * The raw dbus_threads_init() is only useful if you require a
510 * particular thread implementation for some reason.
512 * A possible reason to use dbus_threads_init() rather than
513 * dbus_threads_init_default() is to insert debugging checks or print
516 * dbus_threads_init() may be called more than once. The first one
517 * wins and subsequent calls are ignored. (Unless you use
518 * dbus_shutdown() to reset libdbus, which will let you re-init
521 * Either recursive or nonrecursive mutex functions must be specified,
522 * but not both. New code should provide only the recursive functions
523 * - specifying the nonrecursive ones is deprecated.
525 * Because this function effectively sets global state, all code
526 * running in a given application must agree on the thread
527 * implementation. Most code won't care which thread implementation is
528 * used, so there's no problem. However, usually libraries should not
529 * call dbus_threads_init() or dbus_threads_init_default(), instead
530 * leaving this policy choice to applications.
532 * The exception is for application frameworks (GLib, Qt, etc.) and
533 * D-Bus bindings based on application frameworks. These frameworks
534 * define a cross-platform thread abstraction and can assume
535 * applications using the framework are OK with using that thread
538 * However, even these app frameworks may find it easier to simply call
539 * dbus_threads_init_default(), and there's no reason they shouldn't.
541 * @param functions functions for using threads
542 * @returns #TRUE on success, #FALSE if no memory
545 dbus_threads_init (const DBusThreadFunctions *functions)
547 dbus_bool_t mutex_set;
548 dbus_bool_t recursive_mutex_set;
550 _dbus_assert (functions != NULL);
552 /* these base functions are required. Future additions to
553 * DBusThreadFunctions may be optional.
555 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK);
556 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK);
557 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK);
558 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK);
559 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK);
560 _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK);
561 _dbus_assert (functions->condvar_new != NULL);
562 _dbus_assert (functions->condvar_free != NULL);
563 _dbus_assert (functions->condvar_wait != NULL);
564 _dbus_assert (functions->condvar_wait_timeout != NULL);
565 _dbus_assert (functions->condvar_wake_one != NULL);
566 _dbus_assert (functions->condvar_wake_all != NULL);
568 /* Either the mutex function set or recursive mutex set needs
569 * to be available but not both
571 mutex_set = (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK) &&
572 (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK) &&
573 (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK) &&
574 (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK) &&
575 functions->mutex_new &&
576 functions->mutex_free &&
577 functions->mutex_lock &&
578 functions->mutex_unlock;
580 recursive_mutex_set =
581 (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK) &&
582 (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK) &&
583 (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK) &&
584 (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK) &&
585 functions->recursive_mutex_new &&
586 functions->recursive_mutex_free &&
587 functions->recursive_mutex_lock &&
588 functions->recursive_mutex_unlock;
590 if (!(mutex_set || recursive_mutex_set))
591 _dbus_assert_not_reached ("Either the nonrecusrive or recursive mutex "
592 "functions sets should be passed into "
593 "dbus_threads_init. Neither sets were passed.");
595 if (mutex_set && recursive_mutex_set)
596 _dbus_assert_not_reached ("Either the nonrecusrive or recursive mutex "
597 "functions sets should be passed into "
598 "dbus_threads_init. Both sets were passed. "
599 "You most likely just want to set the recursive "
600 "mutex functions to avoid deadlocks in D-Bus.");
602 /* Check that all bits in the mask actually are valid mask bits.
603 * ensures people won't write code that breaks when we add
606 _dbus_assert ((functions->mask & ~DBUS_THREAD_FUNCTIONS_ALL_MASK) == 0);
608 if (thread_init_generation != _dbus_current_generation)
609 thread_functions.mask = 0; /* allow re-init in new generation */
611 /* Silently allow multiple init
612 * First init wins and D-Bus will always use its threading system
614 if (thread_functions.mask != 0)
617 thread_functions.mutex_new = functions->mutex_new;
618 thread_functions.mutex_free = functions->mutex_free;
619 thread_functions.mutex_lock = functions->mutex_lock;
620 thread_functions.mutex_unlock = functions->mutex_unlock;
622 thread_functions.condvar_new = functions->condvar_new;
623 thread_functions.condvar_free = functions->condvar_free;
624 thread_functions.condvar_wait = functions->condvar_wait;
625 thread_functions.condvar_wait_timeout = functions->condvar_wait_timeout;
626 thread_functions.condvar_wake_one = functions->condvar_wake_one;
627 thread_functions.condvar_wake_all = functions->condvar_wake_all;
629 if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK)
630 thread_functions.recursive_mutex_new = functions->recursive_mutex_new;
632 if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK)
633 thread_functions.recursive_mutex_free = functions->recursive_mutex_free;
635 if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK)
636 thread_functions.recursive_mutex_lock = functions->recursive_mutex_lock;
638 if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK)
639 thread_functions.recursive_mutex_unlock = functions->recursive_mutex_unlock;
641 thread_functions.mask = functions->mask;
646 thread_init_generation = _dbus_current_generation;
653 /* Default thread implemenation */
657 * Calls dbus_threads_init() with a default set of
658 * #DBusThreadFunctions appropriate for the platform.
660 * Most applications should use this rather than dbus_threads_init().
662 * It's safe to call dbus_threads_init_default() as many times as you
663 * want, but only the first time will have an effect.
665 * dbus_shutdown() reverses the effects of this function when it
666 * resets all global state in libdbus.
668 * @returns #TRUE on success, #FALSE if not enough memory
671 dbus_threads_init_default (void)
673 return _dbus_threads_init_platform_specific ();
679 #ifdef DBUS_BUILD_TESTS
680 /** Fake mutex used for debugging */
681 typedef struct DBusFakeMutex DBusFakeMutex;
682 /** Fake mutex used for debugging */
685 dbus_bool_t locked; /**< Mutex is "locked" */
688 static DBusMutex * dbus_fake_mutex_new (void);
689 static void dbus_fake_mutex_free (DBusMutex *mutex);
690 static dbus_bool_t dbus_fake_mutex_lock (DBusMutex *mutex);
691 static dbus_bool_t dbus_fake_mutex_unlock (DBusMutex *mutex);
692 static DBusCondVar* dbus_fake_condvar_new (void);
693 static void dbus_fake_condvar_free (DBusCondVar *cond);
694 static void dbus_fake_condvar_wait (DBusCondVar *cond,
696 static dbus_bool_t dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
699 static void dbus_fake_condvar_wake_one (DBusCondVar *cond);
700 static void dbus_fake_condvar_wake_all (DBusCondVar *cond);
703 static const DBusThreadFunctions fake_functions =
705 DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK |
706 DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK |
707 DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK |
708 DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK |
709 DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK |
710 DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK |
711 DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK |
712 DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK |
713 DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK|
714 DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK,
716 dbus_fake_mutex_free,
717 dbus_fake_mutex_lock,
718 dbus_fake_mutex_unlock,
719 dbus_fake_condvar_new,
720 dbus_fake_condvar_free,
721 dbus_fake_condvar_wait,
722 dbus_fake_condvar_wait_timeout,
723 dbus_fake_condvar_wake_one,
724 dbus_fake_condvar_wake_all
728 dbus_fake_mutex_new (void)
730 DBusFakeMutex *mutex;
732 mutex = dbus_new0 (DBusFakeMutex, 1);
734 return (DBusMutex *)mutex;
738 dbus_fake_mutex_free (DBusMutex *mutex)
740 DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
742 _dbus_assert (!fake->locked);
748 dbus_fake_mutex_lock (DBusMutex *mutex)
750 DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
752 _dbus_assert (!fake->locked);
760 dbus_fake_mutex_unlock (DBusMutex *mutex)
762 DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
764 _dbus_assert (fake->locked);
766 fake->locked = FALSE;
772 dbus_fake_condvar_new (void)
774 return (DBusCondVar*) _dbus_strdup ("FakeCondvar");
778 dbus_fake_condvar_free (DBusCondVar *cond)
784 dbus_fake_condvar_wait (DBusCondVar *cond,
791 dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
799 dbus_fake_condvar_wake_one (DBusCondVar *cond)
805 dbus_fake_condvar_wake_all (DBusCondVar *cond)
811 _dbus_threads_init_debug (void)
813 return dbus_threads_init (&fake_functions);
816 #endif /* DBUS_BUILD_TESTS */