dbus-1.0/dbus/dbus-threads.h

0001 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
0002 /* dbus-threads.h  D-Bus threads handling
0003  *
0004  * Copyright (C) 2002  Red Hat Inc.
0005  *
0006  * Licensed under the Academic Free License version 2.1
0007  *
0008  * This program is free software; you can redistribute it and/or modify
0009  * it under the terms of the GNU General Public License as published by
0010  * the Free Software Foundation; either version 2 of the License, or
0011  * (at your option) any later version.
0012  *
0013  * This program is distributed in the hope that it will be useful,
0014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0016  * GNU General Public License for more details.
0017  *
0018  * You should have received a copy of the GNU General Public License
0019  * along with this program; if not, write to the Free Software
0020  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
0021  *
0022  */
0023 #if !defined (DBUS_INSIDE_DBUS_H) && !defined (DBUS_COMPILATION)
0024 #error "Only <dbus/dbus.h> can be included directly, this file may disappear or change contents."
0025 #endif
0026
0027 #ifndef DBUS_THREADS_H
0028 #define DBUS_THREADS_H
0029
0030 #include <dbus/dbus-macros.h>
0031 #include <dbus/dbus-types.h>
0032
0033 DBUS_BEGIN_DECLS
0034
0035 /**
0036  * @addtogroup DBusThreads
0037  * @{
0038  */
0039
0040 /** An opaque mutex type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
0041 typedef struct DBusMutex DBusMutex;
0042 /** An opaque condition variable type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */
0043 typedef struct DBusCondVar DBusCondVar;
0044
0045 /** Deprecated, provide DBusRecursiveMutexNewFunction instead. */
0046 typedef DBusMutex*  (* DBusMutexNewFunction)    (void);
0047 /** Deprecated, provide DBusRecursiveMutexFreeFunction instead. */
0048 typedef void        (* DBusMutexFreeFunction)   (DBusMutex *mutex);
0049 /** Deprecated, provide DBusRecursiveMutexLockFunction instead. Return value is lock success, but gets ignored in practice. */
0050 typedef dbus_bool_t (* DBusMutexLockFunction)   (DBusMutex *mutex);
0051 /** Deprecated, provide DBusRecursiveMutexUnlockFunction instead. Return value is unlock success, but gets ignored in practice. */
0052 typedef dbus_bool_t (* DBusMutexUnlockFunction) (DBusMutex *mutex);
0053
0054 /** Creates a new recursively-lockable mutex, or returns #NULL if not
0055  * enough memory.  Can only fail due to lack of memory.  Found in
0056  * #DBusThreadFunctions. Do not just use PTHREAD_MUTEX_RECURSIVE for
0057  * this, because it does not save/restore the recursion count when
0058  * waiting on a condition. libdbus requires the Java-style behavior
0059  * where the mutex is fully unlocked to wait on a condition.
0060  */
0061 typedef DBusMutex*  (* DBusRecursiveMutexNewFunction)    (void);
0062 /** Frees a recursively-lockable mutex.  Found in #DBusThreadFunctions.
0063  */
0064 typedef void        (* DBusRecursiveMutexFreeFunction)   (DBusMutex *mutex);
0065 /** Locks a recursively-lockable mutex.  Found in #DBusThreadFunctions.
0066  * Can only fail due to lack of memory.
0067  */
0068 typedef void        (* DBusRecursiveMutexLockFunction)   (DBusMutex *mutex);
0069 /** Unlocks a recursively-lockable mutex.  Found in #DBusThreadFunctions.
0070  * Can only fail due to lack of memory.
0071  */
0072 typedef void        (* DBusRecursiveMutexUnlockFunction) (DBusMutex *mutex);
0073
0074 /** Creates a new condition variable.  Found in #DBusThreadFunctions.
0075  * Can only fail (returning #NULL) due to lack of memory.
0076  */
0077 typedef DBusCondVar*  (* DBusCondVarNewFunction)         (void);
0078 /** Frees a condition variable.  Found in #DBusThreadFunctions.
0079  */
0080 typedef void          (* DBusCondVarFreeFunction)        (DBusCondVar *cond);
0081
0082 /** Waits on a condition variable.  Found in
0083  * #DBusThreadFunctions. Must work with either a recursive or
0084  * nonrecursive mutex, whichever the thread implementation
0085  * provides. Note that PTHREAD_MUTEX_RECURSIVE does not work with
0086  * condition variables (does not save/restore the recursion count) so
0087  * don't try using simply pthread_cond_wait() and a
0088  * PTHREAD_MUTEX_RECURSIVE to implement this, it won't work right.
0089  *
0090  * Has no error conditions. Must succeed if it returns.
0091  */
0092 typedef void          (* DBusCondVarWaitFunction)        (DBusCondVar *cond,
0093                               DBusMutex   *mutex);
0094
0095 /** Waits on a condition variable with a timeout.  Found in
0096  *  #DBusThreadFunctions. Returns #TRUE if the wait did not
0097  *  time out, and #FALSE if it did.
0098  *
0099  * Has no error conditions. Must succeed if it returns.
0100  */
0101 typedef dbus_bool_t   (* DBusCondVarWaitTimeoutFunction) (DBusCondVar *cond,
0102                               DBusMutex   *mutex,
0103                               int          timeout_milliseconds);
0104 /** Wakes one waiting thread on a condition variable.  Found in #DBusThreadFunctions.
0105  *
0106  * Has no error conditions. Must succeed if it returns.
0107  */
0108 typedef void          (* DBusCondVarWakeOneFunction) (DBusCondVar *cond);
0109
0110 /** Wakes all waiting threads on a condition variable.  Found in #DBusThreadFunctions.
0111  *
0112  * Has no error conditions. Must succeed if it returns.
0113  */
0114 typedef void          (* DBusCondVarWakeAllFunction) (DBusCondVar *cond);
0115
0116 /**
0117  * Flags indicating which functions are present in #DBusThreadFunctions. Used to allow
0118  * the library to detect older callers of dbus_threads_init() if new possible functions
0119  * are added to #DBusThreadFunctions.
0120  */
0121 typedef enum
0122 {
0123   DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK      = 1 << 0,
0124   DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK     = 1 << 1,
0125   DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK     = 1 << 2,
0126   DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK   = 1 << 3,
0127   DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK    = 1 << 4,
0128   DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK   = 1 << 5,
0129   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK   = 1 << 6,
0130   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK   = 1 << 7,
0131   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK = 1 << 8,
0132   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK = 1 << 9,
0133   DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK    = 1 << 10,
0134   DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK   = 1 << 11,
0135   DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK   = 1 << 12,
0136   DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK = 1 << 13,
0137   DBUS_THREAD_FUNCTIONS_ALL_MASK     = (1 << 14) - 1
0138 } DBusThreadFunctionsMask;
0139
0140 /**
0141  * Functions that must be implemented to make the D-Bus library
0142  * thread-aware.
0143  *
0144  * If you supply both recursive and non-recursive mutexes,
0145  * libdbus will use the non-recursive version for condition variables,
0146  * and the recursive version in other contexts.
0147  *
0148  * The condition variable functions have to work with nonrecursive
0149  * mutexes if you provide those, or with recursive mutexes if you
0150  * don't.
0151  */
0152 typedef struct
0153 {
0154   unsigned int mask; /**< Mask indicating which functions are present. */
0155
0156   DBusMutexNewFunction mutex_new; /**< Function to create a mutex; optional and deprecated. */
0157   DBusMutexFreeFunction mutex_free; /**< Function to free a mutex; optional and deprecated. */
0158   DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex; optional and deprecated. */
0159   DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex; optional and deprecated. */
0160
0161   DBusCondVarNewFunction condvar_new; /**< Function to create a condition variable */
0162   DBusCondVarFreeFunction condvar_free; /**< Function to free a condition variable */
0163   DBusCondVarWaitFunction condvar_wait; /**< Function to wait on a condition */
0164   DBusCondVarWaitTimeoutFunction condvar_wait_timeout; /**< Function to wait on a condition with a timeout */
0165   DBusCondVarWakeOneFunction condvar_wake_one; /**< Function to wake one thread waiting on the condition */
0166   DBusCondVarWakeAllFunction condvar_wake_all; /**< Function to wake all threads waiting on the condition */
0167
0168   DBusRecursiveMutexNewFunction recursive_mutex_new; /**< Function to create a recursive mutex */
0169   DBusRecursiveMutexFreeFunction recursive_mutex_free; /**< Function to free a recursive mutex */
0170   DBusRecursiveMutexLockFunction recursive_mutex_lock; /**< Function to lock a recursive mutex */
0171   DBusRecursiveMutexUnlockFunction recursive_mutex_unlock; /**< Function to unlock a recursive mutex */
0172
0173   void (* padding1) (void); /**< Reserved for future expansion */
0174   void (* padding2) (void); /**< Reserved for future expansion */
0175   void (* padding3) (void); /**< Reserved for future expansion */
0176   void (* padding4) (void); /**< Reserved for future expansion */
0177
0178 } DBusThreadFunctions;
0179
0180 DBUS_EXPORT
0181 dbus_bool_t  dbus_threads_init         (const DBusThreadFunctions *functions);
0182 DBUS_EXPORT
0183 dbus_bool_t  dbus_threads_init_default (void);
0184
0185 /** @} */
0186
0187 DBUS_END_DECLS
0188
0189 #endif /* DBUS_THREADS_H */