single instance with dbus

[Havoc Pennington]

Hi,

Just reading notification-daemon code, I figured I had better write up 
how this pattern is intended to work, I've seen the details wrong in a 
couple other places too.

If you want only one instance of the bus name to ever exist, you should 
do this:

  - support a --replace command line option
  - on startup, call dbus_bus_request_name() (or the equivalent with
    the bindings you are using). Supply the flags
    DO_NOT_QUEUE, ALLOW_REPLACEMENT, and if --replace was
    specified, REPLACE_EXISTING
  - if you get an error reply (DBusError), exit
  - if you get a result code other than PRIMARY_OWNER or ALREADY_OWNER,
    exit
  - set up a signal handler for the NameLost signal and your bus name,
    and exit if you receive it. This signal is always sent so it is not
    necessary to add a "match rule"

For most daemons the above is correct. --replace is mostly used for 
debugging, but may have other uses.

(notification-daemon developers: the bugs are that you need to check 
request_name_result, need to specify ALLOW_REPLACEMENT, need to handle 
NameLost - I'd file a bug but I'd have to learn Trac ;-)

If you have a "generic" name and multiple apps supporting it might be 
running it at any given time, you might do things differently:

  - use QUEUE mode (pass RequestName flags of 0)
  - you should always get at least queued for the bus name, so just
    request it and don't worry about whether you have it at any given
    time

This is appropriate for a name like TextEditor or Browser where another 
app might want to use "whichever one is open" but it's OK to run two of 
them at once. Both will be queued for the bus name, the last one to 
start will actually own it. If one exits, the other will take over.

For a name you really want to have only one of, though, such as 
"Epiphany" rather than "Browser," you should use the first pattern.

Havoc