X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dbus%2Fdbus-threads.h;h=6d28a0b6312921f50cc9e021770e80cb80a54d4d;hb=61d97215c317a4154df47fbfb882aab60b92fbab;hp=0dcb104032f0e962e780693df13f99ab8e30d219;hpb=fe4018941190f8bf020e4a8ed2999c212e0e113d;p=platform%2Fupstream%2Fdbus.git diff --git a/dbus/dbus-threads.h b/dbus/dbus-threads.h index 0dcb104..6d28a0b 100644 --- a/dbus/dbus-threads.h +++ b/dbus/dbus-threads.h @@ -1,9 +1,9 @@ -/* -*- mode: C; c-file-style: "gnu" -*- */ -/* dbus-threads.h D-BUS threads handling +/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ +/* dbus-threads.h D-Bus threads handling * * Copyright (C) 2002 Red Hat Inc. * - * Licensed under the Academic Free License version 1.2 + * Licensed under the Academic Free License version 2.1 * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -17,7 +17,7 @@ * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * */ #if !defined (DBUS_INSIDE_DBUS_H) && !defined (DBUS_COMPILATION) @@ -30,26 +30,94 @@ #include #include -DBUS_BEGIN_DECLS; +DBUS_BEGIN_DECLS +/** + * @addtogroup DBusThreads + * @{ + */ + +/** An opaque mutex type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */ typedef struct DBusMutex DBusMutex; +/** An opaque condition variable type provided by the #DBusThreadFunctions implementation installed by dbus_threads_init(). */ typedef struct DBusCondVar DBusCondVar; +/** Deprecated, provide DBusRecursiveMutexNewFunction instead. */ typedef DBusMutex* (* DBusMutexNewFunction) (void); +/** Deprecated, provide DBusRecursiveMutexFreeFunction instead. */ typedef void (* DBusMutexFreeFunction) (DBusMutex *mutex); +/** Deprecated, provide DBusRecursiveMutexLockFunction instead. Return value is lock success, but gets ignored in practice. */ typedef dbus_bool_t (* DBusMutexLockFunction) (DBusMutex *mutex); +/** Deprecated, provide DBusRecursiveMutexUnlockFunction instead. Return value is unlock success, but gets ignored in practice. */ typedef dbus_bool_t (* DBusMutexUnlockFunction) (DBusMutex *mutex); +/** 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. + */ +typedef DBusMutex* (* DBusRecursiveMutexNewFunction) (void); +/** Frees a recursively-lockable mutex. Found in #DBusThreadFunctions. + */ +typedef void (* DBusRecursiveMutexFreeFunction) (DBusMutex *mutex); +/** Locks a recursively-lockable mutex. Found in #DBusThreadFunctions. + * Can only fail due to lack of memory. + */ +typedef void (* DBusRecursiveMutexLockFunction) (DBusMutex *mutex); +/** Unlocks a recursively-lockable mutex. Found in #DBusThreadFunctions. + * Can only fail due to lack of memory. + */ +typedef void (* DBusRecursiveMutexUnlockFunction) (DBusMutex *mutex); + +/** Creates a new condition variable. Found in #DBusThreadFunctions. + * Can only fail (returning #NULL) due to lack of memory. + */ typedef DBusCondVar* (* DBusCondVarNewFunction) (void); +/** Frees a condition variable. Found in #DBusThreadFunctions. + */ typedef void (* DBusCondVarFreeFunction) (DBusCondVar *cond); + +/** 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. + */ typedef void (* DBusCondVarWaitFunction) (DBusCondVar *cond, DBusMutex *mutex); + +/** 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. + */ typedef dbus_bool_t (* DBusCondVarWaitTimeoutFunction) (DBusCondVar *cond, DBusMutex *mutex, int timeout_milliseconds); +/** Wakes one waiting thread on a condition variable. Found in #DBusThreadFunctions. + * + * Has no error conditions. Must succeed if it returns. + */ typedef void (* DBusCondVarWakeOneFunction) (DBusCondVar *cond); + +/** Wakes all waiting threads on a condition variable. Found in #DBusThreadFunctions. + * + * Has no error conditions. Must succeed if it returns. + */ typedef void (* DBusCondVarWakeAllFunction) (DBusCondVar *cond); +/** + * 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. + */ typedef enum { DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK = 1 << 0, @@ -62,57 +130,60 @@ typedef enum 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_ALL_MASK = (1 << 10) - 1 + 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 } DBusThreadFunctionsMask; +/** + * Functions that must be implemented to make the D-Bus library + * thread-aware. + * + * If you supply both recursive and non-recursive mutexes, + * libdbus will use the non-recursive version for condition variables, + * and the recursive version in other contexts. + * + * The condition variable functions have to work with nonrecursive + * mutexes if you provide those, or with recursive mutexes if you + * don't. + */ typedef struct { - unsigned int mask; - - DBusMutexNewFunction mutex_new; - DBusMutexFreeFunction mutex_free; - DBusMutexLockFunction mutex_lock; - DBusMutexUnlockFunction mutex_unlock; - - DBusCondVarNewFunction condvar_new; - DBusCondVarFreeFunction condvar_free; - DBusCondVarWaitFunction condvar_wait; - DBusCondVarWaitTimeoutFunction condvar_wait_timeout; - DBusCondVarWakeOneFunction condvar_wake_one; - DBusCondVarWakeAllFunction condvar_wake_all; - - void (* padding1) (void); - void (* padding2) (void); - void (* padding3) (void); - void (* padding4) (void); - void (* padding5) (void); - void (* padding6) (void); - void (* padding7) (void); - void (* padding8) (void); + unsigned int mask; /**< Mask indicating which functions are present. */ + + DBusMutexNewFunction mutex_new; /**< Function to create a mutex; optional and deprecated. */ + DBusMutexFreeFunction mutex_free; /**< Function to free a mutex; optional and deprecated. */ + DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex; optional and deprecated. */ + DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex; optional and deprecated. */ + + DBusCondVarNewFunction condvar_new; /**< Function to create a condition variable */ + DBusCondVarFreeFunction condvar_free; /**< Function to free a condition variable */ + DBusCondVarWaitFunction condvar_wait; /**< Function to wait on a condition */ + DBusCondVarWaitTimeoutFunction condvar_wait_timeout; /**< Function to wait on a condition with a timeout */ + DBusCondVarWakeOneFunction condvar_wake_one; /**< Function to wake one thread waiting on the condition */ + DBusCondVarWakeAllFunction condvar_wake_all; /**< Function to wake all threads waiting on the condition */ + + DBusRecursiveMutexNewFunction recursive_mutex_new; /**< Function to create a recursive mutex */ + DBusRecursiveMutexFreeFunction recursive_mutex_free; /**< Function to free a recursive mutex */ + DBusRecursiveMutexLockFunction recursive_mutex_lock; /**< Function to lock a recursive mutex */ + DBusRecursiveMutexUnlockFunction recursive_mutex_unlock; /**< Function to unlock a recursive mutex */ + + void (* padding1) (void); /**< Reserved for future expansion */ + void (* padding2) (void); /**< Reserved for future expansion */ + void (* padding3) (void); /**< Reserved for future expansion */ + void (* padding4) (void); /**< Reserved for future expansion */ } DBusThreadFunctions; - -DBusMutex* dbus_mutex_new (void); -void dbus_mutex_free (DBusMutex *mutex); -dbus_bool_t dbus_mutex_lock (DBusMutex *mutex); -dbus_bool_t dbus_mutex_unlock (DBusMutex *mutex); - -DBusCondVar* dbus_condvar_new (void); -void dbus_condvar_free (DBusCondVar *cond); -void dbus_condvar_wait (DBusCondVar *cond, - DBusMutex *mutex); -dbus_bool_t dbus_condvar_wait_timeout (DBusCondVar *cond, - DBusMutex *mutex, - int timeout_milliseconds); -void dbus_condvar_wake_one (DBusCondVar *cond); -void dbus_condvar_wake_all (DBusCondVar *cond); - +DBUS_EXPORT dbus_bool_t dbus_threads_init (const DBusThreadFunctions *functions); +DBUS_EXPORT +dbus_bool_t dbus_threads_init_default (void); +/** @} */ - -DBUS_END_DECLS; +DBUS_END_DECLS #endif /* DBUS_THREADS_H */