Thread functions
D-Bus low-level public API

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(). More...
typedef struct DBusCondVar | DBusCondVar
| An opaque condition variable type provided by the DBusThreadFunctions implementation installed by dbus_threads_init(). More...
typedef DBusMutex *(* | DBusMutexNewFunction )(void)
| Deprecated, provide DBusRecursiveMutexNewFunction instead. More...
typedef void(* | DBusMutexFreeFunction )(DBusMutex *mutex)
| Deprecated, provide DBusRecursiveMutexFreeFunction instead. More...
typedef dbus_bool_t(* | DBusMutexLockFunction )(DBusMutex *mutex)
| Deprecated, provide DBusRecursiveMutexLockFunction instead. More...
typedef dbus_bool_t(* | DBusMutexUnlockFunction )(DBusMutex *mutex)
| Deprecated, provide DBusRecursiveMutexUnlockFunction instead. More...
typedef DBusMutex *(* | DBusRecursiveMutexNewFunction )(void)
| Creates a new recursively-lockable mutex, or returns NULL if not enough memory. More...
typedef void(* | DBusRecursiveMutexFreeFunction )(DBusMutex *mutex)
| Frees a recursively-lockable mutex. More...
typedef void(* | DBusRecursiveMutexLockFunction )(DBusMutex *mutex)
| Locks a recursively-lockable mutex. More...
typedef void(* | DBusRecursiveMutexUnlockFunction )(DBusMutex *mutex)
| Unlocks a recursively-lockable mutex. More...
typedef DBusCondVar *(* | DBusCondVarNewFunction )(void)
| Creates a new condition variable. More...
typedef void(* | DBusCondVarFreeFunction )(DBusCondVar *cond)
| Frees a condition variable. More...
typedef void(* | DBusCondVarWaitFunction )(DBusCondVar *cond, DBusMutex *mutex)
| Waits on a condition variable. More...
typedef dbus_bool_t(* | DBusCondVarWaitTimeoutFunction )(DBusCondVar *cond, DBusMutex *mutex, int timeout_milliseconds)
| Waits on a condition variable with a timeout. More...
typedef void(* | DBusCondVarWakeOneFunction )(DBusCondVar *cond)
| Wakes one waiting thread on a condition variable. More...
typedef void(* | DBusCondVarWakeAllFunction )(DBusCondVar *cond)
| Wakes all waiting threads on a condition variable. More...

## 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(). More...
dbus_bool_t | dbus_threads_init_default (void)
| Initializes threads. More...

## Detailed Description

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 Documentation

typedef struct DBusCondVar DBusCondVar

An opaque condition variable type provided by the DBusThreadFunctions implementation installed by dbus_threads_init().

Definition at line 43 of file dbus-threads.h.

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 struct DBusMutex DBusMutex

An opaque mutex type provided by the DBusThreadFunctions implementation installed by dbus_threads_init().

Definition at line 41 of file dbus-threads.h.

typedef void(* DBusMutexFreeFunction)(DBusMutex *mutex)

Deprecated, provide DBusRecursiveMutexFreeFunction instead.

Definition at line 48 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 DBusMutex*(* DBusMutexNewFunction)(void)

Deprecated, provide DBusRecursiveMutexNewFunction instead.

Definition at line 46 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.

## Enumeration Type Documentation

enum DBusThreadFunctionsMask

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.

## Function Documentation

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().

Parameters

  functions | ignored, formerly functions for using threads

Returns
  TRUE on success, FALSE if no memory

Definition at line 585 of file dbus-threads.c.

References _dbus_current_generation, FALSE, and TRUE.

Referenced by _dbus_threads_init_platform_specific().

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. Note that this function must be called BEFORE the second thread is started.

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.

Returns
  TRUE on success, FALSE if not enough memory

Definition at line 617 of file dbus-threads.c.

References _dbus_threads_init_platform_specific().