Data Structures | |
| struct | DBusThreadFunctions |
| Functions that must be implemented to make the D-Bus library thread-aware. More... | |
Typedefs | |
| typedef DBusMutex | DBusMutex |
| An opaque mutex type provided by the DBusThreadFunctions implementation installed by dbus_threads_init(). | |
| typedef DBusCondVar | DBusCondVar |
| An opaque condition variable type provided by the DBusThreadFunctions implementation installed by dbus_threads_init(). | |
| typedef DBusMutex *(*) | DBusMutexNewFunction (void) |
| Deprecated, provide DBusRecursiveMutexNewFunction instead. | |
| typedef void(*) | DBusMutexFreeFunction (DBusMutex *mutex) |
| Deprecated, provide DBusRecursiveMutexFreeFunction instead. | |
| typedef dbus_bool_t(*) | DBusMutexLockFunction (DBusMutex *mutex) |
| Deprecated, provide DBusRecursiveMutexLockFunction instead. | |
| typedef dbus_bool_t(*) | DBusMutexUnlockFunction (DBusMutex *mutex) |
| Deprecated, provide DBusRecursiveMutexUnlockFunction instead. | |
| typedef DBusMutex *(*) | DBusRecursiveMutexNewFunction (void) |
| Creates a new recursively-lockable mutex, or returns NULL if not enough memory. | |
| typedef void(*) | DBusRecursiveMutexFreeFunction (DBusMutex *mutex) |
| Frees a recursively-lockable mutex. | |
| typedef void(*) | DBusRecursiveMutexLockFunction (DBusMutex *mutex) |
| Locks a recursively-lockable mutex. | |
| typedef void(*) | DBusRecursiveMutexUnlockFunction (DBusMutex *mutex) |
| Unlocks a recursively-lockable mutex. | |
| typedef DBusCondVar *(*) | DBusCondVarNewFunction (void) |
| Creates a new condition variable. | |
| typedef void(*) | DBusCondVarFreeFunction (DBusCondVar *cond) |
| Frees a condition variable. | |
| typedef void(*) | DBusCondVarWaitFunction (DBusCondVar *cond, DBusMutex *mutex) |
| Waits on a condition variable. | |
| typedef dbus_bool_t(*) | DBusCondVarWaitTimeoutFunction (DBusCondVar *cond, DBusMutex *mutex, int timeout_milliseconds) |
| Waits on a condition variable with a timeout. | |
| typedef void(*) | DBusCondVarWakeOneFunction (DBusCondVar *cond) |
| Wakes one waiting thread on a condition variable. | |
| typedef void(*) | DBusCondVarWakeAllFunction (DBusCondVar *cond) |
| Wakes all waiting threads on a condition variable. | |
Enumerations | |
| enum | DBusThreadFunctionsMask { DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK = 1 << 0, DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK = 1 << 1, DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK = 1 << 2, DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK = 1 << 3, DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK = 1 << 4, DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK = 1 << 5, DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK = 1 << 6, DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK = 1 << 7, DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK = 1 << 8, DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK = 1 << 9, DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK = 1 << 10, DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK = 1 << 11, DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK = 1 << 12, DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK = 1 << 13, DBUS_THREAD_FUNCTIONS_ALL_MASK = (1 << 14) - 1 } |
| Flags indicating which functions are present in DBusThreadFunctions. More... | |
Functions | |
| dbus_bool_t | dbus_threads_init (const DBusThreadFunctions *functions) |
| Initializes threads. | |
| dbus_bool_t | dbus_threads_init_default (void) |
| Calls dbus_threads_init() with a default set of DBusThreadFunctions appropriate for the platform. | |
Functions and macros related to threads and thread locks.
If threads are initialized, the D-Bus library has locks on all global data structures. In addition, each DBusConnection has a lock, so only one thread at a time can touch the connection. (See DBusConnection for more on connection locking.)
Most other objects, however, do not have locks - they can only be used from a single thread at a time, unless you lock them yourself. For example, a DBusMessage can't be modified from two threads at once.
| typedef void(* ) DBusCondVarFreeFunction(DBusCondVar *cond) |
Frees a condition variable.
Found in DBusThreadFunctions.
Definition at line 80 of file dbus-threads.h.
| typedef DBusCondVar*(* ) DBusCondVarNewFunction(void) |
Creates a new condition variable.
Found in DBusThreadFunctions. Can only fail (returning NULL) due to lack of memory.
Definition at line 77 of file dbus-threads.h.
| typedef void(* ) DBusCondVarWaitFunction(DBusCondVar *cond, DBusMutex *mutex) |
Waits on a condition variable.
Found in DBusThreadFunctions. Must work with either a recursive or nonrecursive mutex, whichever the thread implementation provides. Note that PTHREAD_MUTEX_RECURSIVE does not work with condition variables (does not save/restore the recursion count) so don't try using simply pthread_cond_wait() and a PTHREAD_MUTEX_RECURSIVE to implement this, it won't work right.
Has no error conditions. Must succeed if it returns.
Definition at line 92 of file dbus-threads.h.
| typedef dbus_bool_t(* ) DBusCondVarWaitTimeoutFunction(DBusCondVar *cond, DBusMutex *mutex, int timeout_milliseconds) |
Waits on a condition variable with a timeout.
Found in DBusThreadFunctions. Returns TRUE if the wait did not time out, and FALSE if it did.
Has no error conditions. Must succeed if it returns.
Definition at line 101 of file dbus-threads.h.
| typedef void(* ) DBusCondVarWakeAllFunction(DBusCondVar *cond) |
Wakes all waiting threads on a condition variable.
Found in DBusThreadFunctions.
Has no error conditions. Must succeed if it returns.
Definition at line 114 of file dbus-threads.h.
| typedef void(* ) DBusCondVarWakeOneFunction(DBusCondVar *cond) |
Wakes one waiting thread on a condition variable.
Found in DBusThreadFunctions.
Has no error conditions. Must succeed if it returns.
Definition at line 108 of file dbus-threads.h.
| typedef dbus_bool_t(* ) DBusMutexLockFunction(DBusMutex *mutex) |
Deprecated, provide DBusRecursiveMutexLockFunction instead.
Return value is lock success, but gets ignored in practice.
Definition at line 50 of file dbus-threads.h.
| typedef dbus_bool_t(* ) DBusMutexUnlockFunction(DBusMutex *mutex) |
Deprecated, provide DBusRecursiveMutexUnlockFunction instead.
Return value is unlock success, but gets ignored in practice.
Definition at line 52 of file dbus-threads.h.
| typedef void(* ) DBusRecursiveMutexFreeFunction(DBusMutex *mutex) |
Frees a recursively-lockable mutex.
Found in DBusThreadFunctions.
Definition at line 64 of file dbus-threads.h.
| typedef void(* ) DBusRecursiveMutexLockFunction(DBusMutex *mutex) |
Locks a recursively-lockable mutex.
Found in DBusThreadFunctions. Can only fail due to lack of memory.
Definition at line 68 of file dbus-threads.h.
| typedef DBusMutex*(* ) DBusRecursiveMutexNewFunction(void) |
Creates a new recursively-lockable mutex, or returns NULL if not enough memory.
Can only fail due to lack of memory. Found in DBusThreadFunctions. Do not just use PTHREAD_MUTEX_RECURSIVE for this, because it does not save/restore the recursion count when waiting on a condition. libdbus requires the Java-style behavior where the mutex is fully unlocked to wait on a condition.
Definition at line 61 of file dbus-threads.h.
| typedef void(* ) DBusRecursiveMutexUnlockFunction(DBusMutex *mutex) |
Unlocks a recursively-lockable mutex.
Found in DBusThreadFunctions. Can only fail due to lack of memory.
Definition at line 72 of file dbus-threads.h.
Flags indicating which functions are present in DBusThreadFunctions.
Used to allow the library to detect older callers of dbus_threads_init() if new possible functions are added to DBusThreadFunctions.
Definition at line 121 of file dbus-threads.h.
| dbus_bool_t dbus_threads_init | ( | const DBusThreadFunctions * | functions | ) |
Initializes threads.
If this function is not called, the D-Bus library will not lock any data structures. If it is called, D-Bus will do locking, at some cost in efficiency. Note that this function must be called BEFORE the second thread is started.
Almost always, you should use dbus_threads_init_default() instead. The raw dbus_threads_init() is only useful if you require a particular thread implementation for some reason.
A possible reason to use dbus_threads_init() rather than dbus_threads_init_default() is to insert debugging checks or print statements.
dbus_threads_init() may be called more than once. The first one wins and subsequent calls are ignored. (Unless you use dbus_shutdown() to reset libdbus, which will let you re-init threads.)
Either recursive or nonrecursive mutex functions must be specified, but not both. New code should provide only the recursive functions
Because this function effectively sets global state, all code running in a given application must agree on the thread implementation. Most code won't care which thread implementation is used, so there's no problem. However, usually libraries should not call dbus_threads_init() or dbus_threads_init_default(), instead leaving this policy choice to applications.
The exception is for application frameworks (GLib, Qt, etc.) and D-Bus bindings based on application frameworks. These frameworks define a cross-platform thread abstraction and can assume applications using the framework are OK with using that thread abstraction.
However, even these app frameworks may find it easier to simply call dbus_threads_init_default(), and there's no reason they shouldn't.
| functions | functions for using threads |
Definition at line 545 of file dbus-threads.c.
References _dbus_assert, _dbus_assert_not_reached, _dbus_current_generation, DBusThreadFunctions::condvar_free, DBusThreadFunctions::condvar_new, DBusThreadFunctions::condvar_wait, DBusThreadFunctions::condvar_wait_timeout, DBusThreadFunctions::condvar_wake_all, DBusThreadFunctions::condvar_wake_one, FALSE, DBusThreadFunctions::mask, DBusThreadFunctions::mutex_free, DBusThreadFunctions::mutex_lock, DBusThreadFunctions::mutex_new, DBusThreadFunctions::mutex_unlock, NULL, DBusThreadFunctions::recursive_mutex_free, DBusThreadFunctions::recursive_mutex_lock, DBusThreadFunctions::recursive_mutex_new, DBusThreadFunctions::recursive_mutex_unlock, and TRUE.
Referenced by _dbus_threads_init_platform_specific().
| dbus_bool_t dbus_threads_init_default | ( | void | ) |
Calls dbus_threads_init() with a default set of DBusThreadFunctions appropriate for the platform.
Most applications should use this rather than dbus_threads_init().
It's safe to call dbus_threads_init_default() as many times as you want, but only the first time will have an effect.
dbus_shutdown() reverses the effects of this function when it resets all global state in libdbus.
Definition at line 671 of file dbus-threads.c.
References _dbus_threads_init_platform_specific().
1.5.1