Bug 16924

Note that dbus_shutdown() is optional, it's just for use if you want to try to write code that frees all memory explicitly before the program exits. It doesn't do any "essential" cleanup from an OS or cross-process perspective (if it did, stuff would break as soon as a libdbus-using process died uncleanly).

In any case, the two exits in libdbus I know of are:

 * the one in Disconnected default handler, explained here for example:
    http://bugs.freedesktop.org/show_bug.cgi?id=16338#c1
   (and in the docs)

 * the ones on assertion failure (these are SIGABRT not exit I believe)

If you're hitting either of those, the bug is not the exit... in the first case, the exit is expected and correct unless you replace the default handler with your own; in the second case, there's some root cause to the bug.

Are you saying set_exit_on_disconnect() should be implicitly called by dbus_shutdown() on shared connections to turn off the default Disconnected handler?

You don't really explain why calling set_exit_on_disconnect on a shared connection is bad; yes you'd be modifying a global shared connection, but dbus_shutdown() frees *all* global state and requires you to know that nobody else in the process is using dbus at all, so in this case surely calling set_exit_on_disconnect() is OK, if dbus_shutdown() is OK.

I guess arguably when calling dbus_shutdown() you would always mean to not exit, because why shut down otherwise ... but, it seems a bit magic to say the default Disconnected handler runs, *unless* disconnect happens during shutdown. Certainly the docs are simpler if we say we always run the default handler unless you turn it off.

It's a tricky reentrancy headache that dbus_shutdown() will empty the incoming message queue, this can cause oddness beyond the default disconnected handler - that's only one of the event handlers that could possibly run that could result in surprises. But I'm not sure how to avoid emptying the queue.

Maybe the docs should mention explicitly that dbus_shutdown() will close shared connections and empty their message queues, including processing the Disconnected message, and running any message handlers, including the default Disconnected handler if it's enabled.

Bottom line if there's a change that makes sense here I think it needs some more explanation and analysis. dbus_shutdown() isn't doing an explicit exit, it's just exiting because it drains the incoming queue, and there's a handler that happens to exit. So to avoid that handler will involve some sort of special-case magic.

If we don't change the behaviour to not do this, we should change the documentation to make it not be so astonishing.

Created attachment 106065 [details] [review]
dbus_shutdown: document its effect on shared connections

In practice, the sort of applications that call dbus_shutdown()
(e.g. regression tests) will want to either use private connections,
or turn off exit-on-disconnect on the shared connection, or both.

---

It seems nobody else is ever going to document this so I might as well try it.

Timed out waiting for review, applied the documentation improvement. Please revert if you object. Fixed in git for 1.9.2.