dbus/dbus dbus-connection.c, 1.146, 1.147 dbus-connection.h, 1.46,
1.47 dbus-protocol.h, 1.48, 1.49 dbus-shared.h, 1.9,
1.10 dbus-threads.c, 1.31, 1.32 dbus-threads.h, 1.12,
1.13 dbus-watch.c, 1.21, 1.22
Havoc Pennington
hp at kemper.freedesktop.org
Sat Oct 21 14:57:33 PDT 2006
Update of /cvs/dbus/dbus/dbus
In directory kemper:/tmp/cvs-serv5841/dbus
Modified Files:
dbus-connection.c dbus-connection.h dbus-protocol.h
dbus-shared.h dbus-threads.c dbus-threads.h dbus-watch.c
Log Message:
2006-10-21 Havoc Pennington <hp at redhat.com>
* More documentation - all public API now documented according to
Doxygen
Index: dbus-connection.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.c,v
retrieving revision 1.146
retrieving revision 1.147
diff -u -d -r1.146 -r1.147
--- dbus-connection.c 21 Oct 2006 18:51:30 -0000 1.146
+++ dbus-connection.c 21 Oct 2006 21:57:31 -0000 1.147
@@ -533,7 +533,10 @@
/**
* 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.
*/
Index: dbus-connection.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.h,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -d -r1.46 -r1.47
--- dbus-connection.h 21 Oct 2006 18:51:30 -0000 1.46
+++ dbus-connection.h 21 Oct 2006 21:57:31 -0000 1.47
@@ -59,11 +59,15 @@
{
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;
Index: dbus-protocol.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-protocol.h,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- dbus-protocol.h 20 Oct 2006 03:04:59 -0000 1.48
+++ dbus-protocol.h 21 Oct 2006 21:57:31 -0000 1.49
@@ -41,9 +41,10 @@
* @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 @@
#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 @@
#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"
Index: dbus-shared.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-shared.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- dbus-shared.h 20 Oct 2006 03:04:59 -0000 1.9
+++ dbus-shared.h 21 Oct 2006 21:57:31 -0000 1.10
@@ -40,9 +40,12 @@
* @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
* @{
*/
Index: dbus-threads.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-threads.c,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -d -r1.31 -r1.32
--- dbus-threads.c 20 Oct 2006 05:16:58 -0000 1.31
+++ dbus-threads.c 21 Oct 2006 21:57:31 -0000 1.32
@@ -520,18 +520,44 @@
/**
*
- * 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 @@
* 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
Index: dbus-threads.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-threads.h,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- dbus-threads.h 21 Oct 2006 18:17:02 -0000 1.12
+++ dbus-threads.h 21 Oct 2006 21:57:31 -0000 1.13
@@ -37,29 +37,61 @@
* @{
*/
+/** 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 @@
} 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 */
Index: dbus-watch.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-watch.c,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -d -r1.21 -r1.22
--- dbus-watch.c 21 Oct 2006 17:08:08 -0000 1.21
+++ dbus-watch.c 21 Oct 2006 21:57:31 -0000 1.22
@@ -483,6 +483,9 @@
/**
* 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.
*/
More information about the dbus-commit
mailing list