D-Bus: Thread functions

D-Bus 1.14.10

Data Structures | Typedefs | Enumerations | Functions
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().
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.

## 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

## ◆ DBusCondVar

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.

## ◆ DBusCondVarFreeFunction

typedef void(* DBusCondVarFreeFunction) (DBusCondVar *cond)

Frees a condition variable.

Found in DBusThreadFunctions.

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

## ◆ DBusCondVarNewFunction

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.

## ◆ DBusCondVarWaitFunction

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.

## ◆ DBusCondVarWaitTimeoutFunction

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.

## ◆ DBusCondVarWakeAllFunction

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.

## ◆ DBusCondVarWakeOneFunction

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.

## ◆ DBusMutex

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.

## ◆ DBusMutexFreeFunction

typedef void(* DBusMutexFreeFunction) (DBusMutex *mutex)

Deprecated, provide DBusRecursiveMutexFreeFunction instead.

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

## ◆ DBusMutexLockFunction

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.

## ◆ DBusMutexNewFunction

typedef DBusMutex *(* DBusMutexNewFunction) (void)

Deprecated, provide DBusRecursiveMutexNewFunction instead.

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

## ◆ DBusMutexUnlockFunction

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.

## ◆ DBusRecursiveMutexFreeFunction

typedef void(* DBusRecursiveMutexFreeFunction) (DBusMutex *mutex)

Frees a recursively-lockable mutex.

Found in DBusThreadFunctions.

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

## ◆ DBusRecursiveMutexLockFunction

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.

## ◆ DBusRecursiveMutexNewFunction

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.

## ◆ DBusRecursiveMutexUnlockFunction

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

## ◆ DBusThreadFunctionsMask

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

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 393 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_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.

Returns
  TRUE on success, FALSE if not enough memory

Definition at line 440 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().