Proposing ObjectManager interface
David Zeuthen
zeuthen at gmail.com
Tue Mar 1 06:40:16 PST 2011
Hi,
On Tue, Mar 1, 2011 at 9:14 AM, Simon McVittie
<simon.mcvittie at collabora.co.uk> wrote:
> 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 :-)
Sure, I'll file a bug.
>> 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
I don't think we want to filter on interface as well - the whole point
of ObjectManager is that you do the Bus.AddMatch() and
ObjectManager.GetAll() calls (in that order) and that's it... after
this, you *never* need to do more method calls since you receive all
the signals you need to reliably track property state and signal
emissions. In particular you can create new client-side proxies
without any IO upon receiving the InterfacesAdded() signal. Which
means that the implementation is super-simple and thus, super-robust.
> 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"?
I'd be fine with that.
> (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].)
Indeed. On that note, I'd also wish that the interface the bus
implements would be org.freedesktop.DBus.Bus instead of
org.freedesktop.DBus (would have to implement both interfaces for
fallback). Because the current name only helps reinforce the bad
behavior that people say "this app uses D-Bus to do XYZ" when it's
more precise to actually say "this app uses the system bus to do XYZ"
and so on. </rant>
> [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<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> 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.
Hmm, ListObjects() sounds more like.. listing stuff.. I mean, we're
getting the whole thing.. so I'd prefer Get instead of List.. Hmm, for
now, I'll change it to GetManagedObjects() - let's continue discussing
in bugzilla if there's a better idea!
>
>> + The return value of this method is a dict of all object
>> + paths.
>
> nitpicking: a dict whose keys are object paths
Sure.
>> 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?
No... but it's recommended that apps work this way cf. the SHOULD NOT
clause discussed below.
>> + <para>
>> + Changes are emitted using the following two signals:
>> + </para>
>> + <para>
>> + <programlisting>
>> + org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
>> + DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties);
>> + org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
>> + ARRAY<STRING> 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.
OK, I'll add something.
>> + <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).
Yeah, I'll try to reword it with fewer negations...
> 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.
It already says "An application can make use of this interface". I'll
inject "optionally" between 'can' and 'make'.
I'll follow up in bugzilla with a revised patch. Thanks for the review so far.
David
More information about the dbus
mailing list