Should GetManagedObjects include the current path?

[Simon McVittie]

On Sat, 19 Oct 2019 at 22:18:26 +0200, David Henningsson wrote:
> Suppose we have two paths, /hello and /hello/world, where /hello implements
> org.freedesktop.DBus.ObjectManager. When GetManagedObjects is called on
> /hello, should it return data for both /hello and /hello/world, or just
> /hello/world?

I would expect just /hello/world, because ObjectManager is designed
for situations where a service manages a collection of similar objects
(windows, documents, pictures, communication channels, whatever). If
/hello is conceptually a "document manager" that manages a collection of
documents, then /hello is probably not itself a document, so it should
not usually list itself as a child.

This might help:
https://dbus.freedesktop.org/doc/dbus-api-design.html#interface-object-manager

>  - When calling AddMatch, the "path_namespace" in the example a few lines
> below is written so that it does include the path itself

If you are interested in the objects managed by the object manager, you
also need to pay attention to signals emitted by the object manager itself,
because newly created objects are signalled by InterfacesAdded from the
object manager, and deleted objects are signalled by InterfacesRemoved
from the object manager.

Also, in general signal subscription is designed so that it is harmless
to receive and ignore signals that you weren't expecting (minimizing
the signals you receive is a good performance and power consumption
optimization, but is not strictly required). If your process contains more
than one D-Bus client sharing a connection, you will in fact be receiving
the union of all the signals requested by any of those D-Bus clients.

Some past D-Bus implementations have even used bloom filters (a
probabilistic data structure) instead of an exact data structure for
signal matching, which means you are guaranteed to receive all the signals
you subscribed to, but you also receive a small number of signals that
you didn't subscribe to.

>  - The last part is not true for the root path "/", because if ObjectManager
> is implemented on "/", then "/" + "/" = "//" so this needs special handling

Yes, that's true. But D-Bus API designers probably shouldn't do this
anyway, because if one API (let's say "document manager") says "/" is
an ObjectManager for a collection of document objects, and another API
(let's say "communication channel manager") says "/" is an ObjectManager
for a collection of communication channels, and you are writing a
document-sharing service that uses both documents and communication
channels, then you're stuck. The closest you can get to implementing
both APIs correctly is that clients that try to list either documents
or communication channels get a list containing both, which is not what
they will be expecting.

Normally you would implement "document manager" at an entry-point object
path like /com/example/DocumentManager1, "communication channel manager"
at /net/example/ChannelManager1, and so on (where the reversed domain
name like example.com belongs to the designer of each API). Each path
describes its own collection of objects and they do not collide.

If you use GNOME, you can see this by inspecting GNOME Shell in d-feet:
it implements many D-Bus interfaces, which can easily coexist because
none of them are on "/".

See https://dbus.freedesktop.org/doc/dbus-api-design.html#naming-conventions
and https://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning
for more on this topic.

    smcv