[PATCH] Iteration wakeup

[Fan Wu]

Sorry there is a typo in the documentation part of the previous email.
Please look at this one instead. Thanks,
Fan

@@ -2894,6 +2897,31 @@ dbus_connection_get_server_id (DBusConne
 }

 /**
+ * This function is used in multi-threaded environment to wakeup a DBUS
+ * thread if it's blocking with poll/select. Please refer to
+ * the documentation of dbus_connection_read_write_dispatch() for more
+ * information.
+ *
+ * @param connection the connection.
+ */
+
+void
+dbus_connection_interrupt_blocking (DBusConnection* connection)
+{
+    dbus_bool_t executed = FALSE;
+
+    if (NULL == connection)
+       return executed;
+
+    CONNECTION_LOCK (connection);
+    executed = _dbus_transport_wakeup_iteration (connection->transport);
+    CONNECTION_UNLOCK (connection);
+
+    return executed;
+}
+
+
+/**
  * Set whether _exit() should be called when the connection receives a
  * disconnect signal. The call to _exit() comes after any handlers for
  * the disconnect signal run; handlers can cancel the exit by calling
@@ -3420,13 +3448,14 @@ _dbus_connection_read_write_dispatch (DB
  * example usage would be:
  *
  * @code
- *   while (dbus_connection_read_write_dispatch (connection, -1))
+ *   while (loop_flag && dbus_connection_read_write_dispatch (connection, -1))
  *     ; // empty loop body
  * @endcode
  *
  * In this usage you would normally have set up a filter function to look
- * at each message as it is dispatched. The loop terminates when the last
- * message from the connection (the disconnected signal) is processed.
+ * at each message as it is dispatched. If there are no interruptions,
+ * the loop terminates when the last message from the connection
+ * (the disconnected signal) is processed.
  *
  * If there are messages to dispatch, this function will
  * dbus_connection_dispatch() once, and return. If there are no
@@ -3434,10 +3463,18 @@ _dbus_connection_read_write_dispatch (DB
  * write, then read or write, then return.
  *
  * The way to think of this function is that it either makes some sort
- * of progress, or it blocks. Note that, while it is blocked on I/O, it
- * cannot be interrupted (even by other threads), which makes this function
- * unsuitable for applications that do more than just react to received
- * messages.
+ * of progress, or it blocks. The blocking can be interrupted when
+ * other threads attempt to send out messages through the same connection, or
+ * dbus_connection_interrupt_blocking() is called from another thread.
+ *
+ * If your application is both a service provider (react on incoming messages)
+ * and a service consumer (send requests to services provided by others),
+ * you might want to have a thread dedicated to the service provider which
+ * runs the dbus_connection_read_write_dispatch() loop as indicated in the
+ * code example above. While from other threads you can send out requests
+ * any time you want. When the application is about to exit, you shall
+ * set the loop_flag to FALSE, and then call
dbus_connection_interrupt_blocking()
+ * just in case the service provider thread is still blocking.
  *
  * The return value indicates whether the disconnect message has been
  * processed, NOT whether the connection is connected. This is