Proposing ObjectManager interface

[Simon McVittie]

On Mon, 28 Feb 2011 at 17:20:45 -0500, David Zeuthen wrote:
> Here's a patch for the spec for the ObjectManager interface.

fd.o bug number or it didn't happen :-)

> Right now GDBusProxyManager just listen to all signals emitted by the
> name. Which isn't really optimal at all...

You really don't want that in something like Telepathy, where objects have
many interfaces and each client is only likely to be interested in a subset.

dbus-glib has historically used one match rule per (sender, object, interface)
tuple, and I think that often makes sense. Telepathy is designed such that
that granularity should work well: if things naturally go together, we put
them on the same interface, and if you're likely to want one part but not the
other, we split them. 

We have a dbus-glib bug open asking for *more* specific signal-match rules, to
reduce wakeups [23846]; Will and I are of the opinion that that's going too
far, except for the special case of o.fd.DBus (where NameOwnerChanged is
frequent).

If you're going to apply wildcard matches for "all signals in this subtree",
I think they should probably also be filtered by interface; when doing
something like Telepathy with several clients interested in different subsets
of functionality, on an N900 or similar, excess wakeups do matter.

[23846] https://bugs.freedesktop.org/show_bug.cgi?id=23846

Regarding the patch, some brief thoughts:

> +    <sect2 id="standard-interfaces-objectmanager">
> +      <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>

Somewhat off-topic, but [19782] requests that we ship spec-to-docbook.xsl with
libdbus. I've been wondering whether it'd be good to split out the standard
interfaces (particularly Peer and Introspectable) into separate files in
the augmented Introspect() format understood by spec-to-docbook.xsl, with
their output xinclude'd into the D-Bus Specification so they turn up as
"chapters"?

(It'd also make sense to have a clear division between "interfaces anyone can
implement" and "interfaces the bus daemon implements", which both live in the
o.fd.DBus namespace - particularly if we're going to merge [Stats].)

[19782] https://bugs.freedesktop.org/show_bug.cgi?id=19782
[Stats] https://bugs.freedesktop.org/show_bug.cgi?id=34040

> +          org.freedesktop.DBus.ObjectManager.GetAll (out DICT&lt;OBJPATH,DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);

This is bad for bindings where clashing method names in different interfaces
cause difficulties (meaning at least dbus-python), and I think it's easier to
discuss methods if they "usually" have distinct names. I'd call it
ListObjects.

> +        The return value of this method is a dict of all object
> +        paths.

nitpicking: a dict whose keys are object paths

> All returned object paths are children of the object
> +        path implementing this interface.

Is the implication two-way, i.e. are all children guaranteed to be listed?

> +      <para>
> +        Changes are emitted using the following two signals:
> +      </para>
> +      <para>
> +        <programlisting>
> +          org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
> +                                                              DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt; interfaces_and_properties);
> +          org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
> +                                                                ARRAY&lt;STRING&gt; interfaces);
> +        </programlisting>
> +      </para>

I think the signals deserve to be documented at the same conceptual level as
the method, like they are in Introspect() XML.

> +      <para>
> +        Applications SHOULD NOT export objects that are children of an
> +        object (directly or otherwise) implementing this interface but
> +        which are not returned in the reply from the
> +        <literal>GetAll()</literal> method of this interface on the
> +        given object.

OK, so that answers that question (although the wording seems a bit awkward).

I think it'd be worth saying explicitly that in general, objects aren't
required to implement ObjectManager, but that the definition of an interface
may say that it's required for implementations of that interface. Also the
same for Properties, if it doesn't already say so.

    S