diff options
Diffstat (limited to 'dbus')
| -rw-r--r-- | dbus/dbus-connection.c | 5 | ||||
| -rw-r--r-- | dbus/dbus-connection.h | 12 | ||||
| -rw-r--r-- | dbus/dbus-protocol.h | 16 | ||||
| -rw-r--r-- | dbus/dbus-shared.h | 7 | ||||
| -rw-r--r-- | dbus/dbus-threads.c | 52 | ||||
| -rw-r--r-- | dbus/dbus-threads.h | 45 | ||||
| -rw-r--r-- | dbus/dbus-watch.c | 3 |
7 files changed, 114 insertions, 26 deletions
diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 9cd645b8..acba9ba9 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -533,7 +533,10 @@ _dbus_connection_has_messages_to_send_unlocked (DBusConnection *connection) /** * Checks whether there are messages in the outgoing message queue. - * + * Use dbus_connection_flush() to block until all outgoing + * messages have been written to the underlying transport + * (such as a socket). + * * @param connection the connection. * @returns #TRUE if the outgoing queue is non-empty. */ diff --git a/dbus/dbus-connection.h b/dbus/dbus-connection.h index 401154c1..7d775a2f 100644 --- a/dbus/dbus-connection.h +++ b/dbus/dbus-connection.h @@ -59,11 +59,15 @@ typedef enum { DBUS_WATCH_READABLE = 1 << 0, /**< As in POLLIN */ DBUS_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */ - DBUS_WATCH_ERROR = 1 << 2, /**< As in POLLERR (can't watch for this, but - * the flag can be passed to dbus_watch_handle()). + DBUS_WATCH_ERROR = 1 << 2, /**< As in POLLERR (can't watch for + * this, but can be present in + * current state passed to + * dbus_watch_handle()). */ - DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for it, but - * can be present in current state). + DBUS_WATCH_HANGUP = 1 << 3 /**< As in POLLHUP (can't watch for + * it, but can be present in current + * state passed to + * dbus_watch_handle()). */ } DBusWatchFlags; diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h index a36e67c3..6198fd88 100644 --- a/dbus/dbus-protocol.h +++ b/dbus/dbus-protocol.h @@ -41,9 +41,10 @@ extern "C" { * @defgroup DBusProtocol Protocol constants * @ingroup DBus * - * D-Bus protocol constants + * @brief Defines constants which are part of the D-Bus protocol + * + * This header is intended for use by any library, not only libdbus. * - * @brief Defines constants which are part of the D-Bus protocol * @{ */ @@ -349,7 +350,11 @@ extern "C" { #define DBUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" /** Unable to connect to server (probably caused by ECONNREFUSED on a socket). */ #define DBUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" -/** Certain timeout errors, possibly ETIMEDOUT on a socket. Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts. */ +/** Certain timeout errors, possibly ETIMEDOUT on a socket. + * Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts. + * @warning this is confusingly-named given that #DBUS_ERROR_TIMED_OUT also exists. We can't fix + * it for compatibility reasons so just be careful. + */ #define DBUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" /** No network access (probably ENETUNREACH on a socket). */ #define DBUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" @@ -365,7 +370,10 @@ extern "C" { #define DBUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" /** Method name you invoked isn't known by the object you invoked it on. */ #define DBUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" -/** Certain other timeout errors, e.g. while starting a service. @todo redundant with #DBUS_ERROR_TIMEOUT */ +/** Certain timeout errors, e.g. while starting a service. + * @warning this is confusingly-named given that #DBUS_ERROR_TIMEOUT also exists. We can't fix + * it for compatibility reasons so just be careful. + */ #define DBUS_ERROR_TIMED_OUT "org.freedesktop.DBus.Error.TimedOut" /** Tried to remove or modify a match rule that didn't exist. */ #define DBUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" diff --git a/dbus/dbus-shared.h b/dbus/dbus-shared.h index 78d305ef..6d9284e7 100644 --- a/dbus/dbus-shared.h +++ b/dbus/dbus-shared.h @@ -40,9 +40,12 @@ extern "C" { * @defgroup DBusShared Shared constants * @ingroup DBus * - * Shared constants. + * @brief Shared header included by both libdbus and C/C++ bindings such as the GLib bindings. + * + * Usually a C/C++ binding such as the GLib or Qt binding won't want to include dbus.h in its + * public headers. However, a few constants and macros may be useful to include; those are + * found here and in dbus-protocol.h * - * @brief Stuff used by both dbus/dbus.h low-level and C/C++ binding APIs * @{ */ diff --git a/dbus/dbus-threads.c b/dbus/dbus-threads.c index 702cbda7..1fbf48b6 100644 --- a/dbus/dbus-threads.c +++ b/dbus/dbus-threads.c @@ -520,18 +520,44 @@ init_locks (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. + * 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. * - * Use dbus_threads_init_default() if you don't need a - * particular thread implementation. + * Almost always, you should use dbus_threads_init_default() instead. + * The raw dbus_threads_init() is only useful if you require a + * particular thread implementation for some reason. * - * This function may be called more than once. The first - * one wins. + * A possible reason to use dbus_threads_init() rather than + * dbus_threads_init_default() is to insert debugging checks or print + * statements. * + * dbus_threads_init() may be called more than once. The first one + * wins and subsequent calls are ignored. (Unless you use + * dbus_shutdown() to reset libdbus, which will let you re-init + * threads.) + * + * Either recursive or nonrecursive mutex functions must be specified, + * but not both. New code should provide only the recursive functions + * - specifying the nonrecursive ones is deprecated. + * + * Because this function effectively sets global state, all code + * running in a given application must agree on the thread + * implementation. Most code won't care which thread implementation is + * used, so there's no problem. However, usually libraries should not + * call dbus_threads_init() or dbus_threads_init_default(), instead + * leaving this policy choice to applications. + * + * The exception is for application frameworks (GLib, Qt, etc.) and + * D-Bus bindings based on application frameworks. These frameworks + * define a cross-platform thread abstraction and can assume + * applications using the framework are OK with using that thread + * abstraction. + * + * However, even these app frameworks may find it easier to simply call + * dbus_threads_init_default(), and there's no reason they shouldn't. + * * @param functions functions for using threads * @returns #TRUE on success, #FALSE if no memory */ @@ -983,6 +1009,14 @@ static const DBusThreadFunctions internal_functions = * Calls dbus_threads_init() with a default set of * #DBusThreadFunctions appropriate for the platform. * + * Most applications should use this rather than dbus_threads_init(). + * + * 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 */ dbus_bool_t diff --git a/dbus/dbus-threads.h b/dbus/dbus-threads.h index ff3a371b..344b0ffd 100644 --- a/dbus/dbus-threads.h +++ b/dbus/dbus-threads.h @@ -37,29 +37,61 @@ DBUS_BEGIN_DECLS * @{ */ +/** 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. */ typedef dbus_bool_t (* DBusMutexLockFunction) (DBusMutex *mutex); +/** Deprecated, provide DBusRecursiveMutexUnlockFunction instead. */ typedef dbus_bool_t (* DBusMutexUnlockFunction) (DBusMutex *mutex); +/** Creates a new recursively-lockable mutex, or returns #NULL if not enough memory. + * Found in #DBusThreadFunctions + */ 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. + */ typedef void (* DBusRecursiveMutexLockFunction) (DBusMutex *mutex); +/** Unlocks a recursively-lockable mutex. Found in #DBusThreadFunctions. + */ typedef void (* DBusRecursiveMutexUnlockFunction) (DBusMutex *mutex); +/** Creates a new condition variable. Found in #DBusThreadFunctions. + */ typedef DBusCondVar* (* DBusCondVarNewFunction) (void); +/** Frees a condition variable. Found in #DBusThreadFunctions. + */ typedef void (* DBusCondVarFreeFunction) (DBusCondVar *cond); +/** Waits on a condition variable. Found in #DBusThreadFunctions. + */ typedef void (* DBusCondVarWaitFunction) (DBusCondVar *cond, DBusMutex *mutex); +/** Waits on a condition variable with a timeout. Found in #DBusThreadFunctions. + */ typedef dbus_bool_t (* DBusCondVarWaitTimeoutFunction) (DBusCondVar *cond, DBusMutex *mutex, int timeout_milliseconds); +/** Wakes one waiting thread on a condition variable. Found in #DBusThreadFunctions. + */ typedef void (* DBusCondVarWakeOneFunction) (DBusCondVar *cond); +/** Wakes all waiting threads on a condition variable. Found in #DBusThreadFunctions. + */ 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, @@ -80,17 +112,18 @@ typedef enum } DBusThreadFunctionsMask; /** - * Functions that must be implemented to make the D-Bus - * library thread-aware. + * Functions that must be implemented to make the D-Bus library + * thread-aware. The recursive mutex functions should be specified + * rather than the old, deprecated nonrecursive ones. */ typedef struct { unsigned int mask; /**< Mask indicating which functions are present. */ - DBusMutexNewFunction mutex_new; /**< Function to create a mutex */ - DBusMutexFreeFunction mutex_free; /**< Function to free a mutex */ - DBusMutexLockFunction mutex_lock; /**< Function to lock a mutex */ - DBusMutexUnlockFunction mutex_unlock; /**< Function to unlock a mutex */ + 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 */ diff --git a/dbus/dbus-watch.c b/dbus/dbus-watch.c index ebbb7ed2..f2691c82 100644 --- a/dbus/dbus-watch.c +++ b/dbus/dbus-watch.c @@ -483,6 +483,9 @@ _dbus_watch_set_handler (DBusWatch *watch, /** * Gets the file descriptor that should be watched. * + * On Windows, this will be a socket. On UNIX right now it will be a + * socket but in principle it could be something else. + * * @param watch the DBusWatch object. * @returns the file descriptor to watch. */ |