Raw libdbus dispatching

[Havoc Pennington]

Thiago Macieira wrote:
> 
> Interesting, I didn't know this function existed. It really helps me and 
> should help Peter too. Will this function be called from handle_watch?
>

It should be, yes. Anytime the result of get_dispatch_status() will have 
changed, it is supposed to be called.

The only trick about it is that since it's called synchronously from any 
function that creates a need to dispatch, it can be called in surprising 
contexts. i.e. you really want to avoid doing much in this callback 
except to somehow queue up a dispatch for later.

In particular, simple apps might be tempted to 
dbus_connection_dispatch() from inside the dispatch status callback, but 
I'm pretty sure this would result in problems.

Oh, perhaps worse - the dispatch status function can be called from any 
thread that uses the connection. That's kind of nasty but I'm not sure 
how to get around it.

> The dispatching code is one of the oldest code sections remaining in 
> QtDBus, originally written by Harald Fernengel, a long while ago. He 
> probably even based it on Zack Rusin's code, which is now over 3 years 
> old.

Right, set_dispatch_status_function() didn't originally exist.

I think reorganizing the Doxygen groups would help a lot with the main 
loop API, move dbus_watch_* dbus_timeout_* and the relevant 
dbus_connection_set_*_function*() into a separate group, which would 
both de-clutter the DBusConnection group and make it easy to find the 
"hooking up to the main loop" part of the API...

Havoc