|
D-Bus 1.16.0
|
dbus_threads_init() and dbus_threads_init_default() More...
Data Structures | |
| struct | DBusThreadFunctions |
| Functions that must be implemented to make the D-Bus library thread-aware. More... | |
Typedefs | |
| typedef struct DBusMutex | DBusMutex |
| An opaque mutex type provided by the DBusThreadFunctions implementation installed by dbus_threads_init(). | |
| typedef struct 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, like dbus_threads_init_default(). | |
| dbus_bool_t | dbus_threads_init_default (void) |
| Initializes threads. | |
dbus_threads_init() and dbus_threads_init_default()
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 struct DBusCondVar DBusCondVar |
An opaque condition variable type provided by the DBusThreadFunctions implementation installed by dbus_threads_init().
Definition at line 45 of file dbus-threads.h.
| typedef void(* DBusCondVarFreeFunction) (DBusCondVar *cond) |
Frees a condition variable.
Found in DBusThreadFunctions.
Definition at line 82 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 79 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 94 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 103 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 116 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 110 of file dbus-threads.h.
An opaque mutex type provided by the DBusThreadFunctions implementation installed by dbus_threads_init().
Definition at line 43 of file dbus-threads.h.
| typedef void(* DBusMutexFreeFunction) (DBusMutex *mutex) |
Deprecated, provide DBusRecursiveMutexFreeFunction instead.
Definition at line 50 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 52 of file dbus-threads.h.
| typedef DBusMutex *(* DBusMutexNewFunction) (void) |
Deprecated, provide DBusRecursiveMutexNewFunction instead.
Definition at line 48 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 54 of file dbus-threads.h.
| typedef void(* DBusRecursiveMutexFreeFunction) (DBusMutex *mutex) |
Frees a recursively-lockable mutex.
Found in DBusThreadFunctions.
Definition at line 66 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 70 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 63 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 74 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 123 of file dbus-threads.h.
| DBUS_EXPORT dbus_bool_t dbus_threads_init | ( | const DBusThreadFunctions * | functions | ) |
Initializes threads, like dbus_threads_init_default().
This version previously allowed user-specified threading primitives, but since D-Bus 1.6 it ignores them and behaves exactly like dbus_threads_init_default().
| functions | ignored, formerly functions for using threads |
Definition at line 395 of file dbus-threads.c.
References _dbus_current_generation, _dbus_threads_init_platform_specific(), _dbus_threads_lock_platform_specific(), _dbus_threads_unlock_platform_specific(), FALSE, and TRUE.
Referenced by dbus_threads_init_default().
| DBUS_EXPORT dbus_bool_t dbus_threads_init_default | ( | void | ) |
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.
Since D-Bus 1.7 it is safe to call this function from any thread, any number of times (but it must be called before any other libdbus API is used).
In D-Bus 1.6 or older, this function must be called in the main thread before any other thread starts. As a result, it is not sufficient to call this function in a library or plugin, unless the library or plugin imposes a similar requirement on its callers.
dbus_shutdown() reverses the effects of this function when it resets all global state in libdbus.
Definition at line 442 of file dbus-threads.c.
References dbus_threads_init(), and NULL.
Referenced by _dbus_cmutex_new_at_location(), _dbus_condvar_new(), and _dbus_rmutex_new_at_location().
1.9.8