[PATCH] Iteration wakeup

[Fan Wu]

Hi Havoc,

thanks again for the comments.

> Is this a race? I would think it has to be unless is_polling is
> protected by a lock, but since we're doing wakeup() we can't have the io
> path lock at this point, right? So what lock protects is_polling?
>
> There's no real need to avoid the wakeup I don't think, because we only
> need to do the wakeup if we fail to acquire the IO path lock. So usually
> we won't do the wakeup anyway.

The is_polling is protected by the connection lock. If we remove this
and solely rely on IO path lock,  then another thread which is sending
messages can also lock the IO path and cause us to call wakeup. It's
not a big deal other than wasting several CPU cycles, but if possible
I hope we can save that.

I also updated the documentation of
dbus_connection_read_write_dispatch()  along with
dbus_connection_interrupt_blocking(), hopefully make the use case
scenario more clear. Please review.

Thanks,
Fan

 /**
+ * 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
+ * new messages are added to the outgoing queue of the 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_interrupt_blocking() 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