Semantics of o.fd.DBus.Properties

[Simon McVittie]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Thu, 07 Feb 2008 at 16:41:13 -0500, Havoc Pennington wrote:
> On Feb 7, 2008 4:09 PM, Simon McVittie <simon.mcvittie at collabora.co.uk> wrote:
> > dbus-glib has taken that concept and run with it, to the extent that a
> > D-Bus property called, say, "com.example.Anything.BongHits" (with any
> > interface!) is automatically and unavoidably mapped to the "bong-hits" GLib
> > property. This is rather ludicrous as a basis for an interoperable
> > properties system. I haven't tried, but I suspect you can cause many
> > GLib services to assert via this mechanism, which is somewhat unhelpful.
> 
> I think this is a problem with the GLib bindings.

Agreed, and I'll try to fix them.

> My view is that a
> GObject that implements a dbus interface would normally be written for
> that purpose (i.e. I don't believe arbitrary GObject would normally be
> exported). But also there should be some mechanism to exclude signals
> and props that should not be exported.

In Telepathy, we do indeed write GObjects specifically to be exported,
but those GObjects have both a C and a D-Bus API, which usually ought to
be different. For instance, they have a lot of construct-only properties
(so other C code in the same process can instantiate them) that
shouldn't necessarily be on D-Bus.

I think the model should be "only export signals and properties where
that was requested" rather than "export signals and properties unless
told otherwise", although this is mainly a usability difference.

> > This also prevents APIs that have the same property name in multiple
> > interfaces, which is obviously undesirable.
> 
> The same name in multiple interfaces (whether for properties or
> methods) I think can be expected to cause problems for at least some
> bindings almost always; while we did not ban it on the dbus protocol
> level, I would not say it's advisable to create the situation when it
> can be helped.

Right. This is a general complaint I have with the D-Bus spec - it tells
you everything D-Bus can do (gives binding authors something to aim
for), but it doesn't tell D-Bus API designers what they can get away
with and what they should avoid.

Most of my concerns about properties are from my point of view as an
author of the Telepathy D-Bus API, a specification that's intended to have
third-party implementations (both client and service) - there's no point
in me designing a wonderfully clean API if it turns out not to be
implementable in half the bindings!

> > * Are "complete" bindings required to support properties of the same name
> >   in different interfaces?
> 
> As an aside, the spec, in general, says pretty much nothing at all
> about bindings - what it does say is pure guideline. There may be a
> role for some kind of separate "how to do a binding" / "how to be
> interoperable" spec, or section in the current spec.

See above. It would be extremely helpful for specification authors to be
able to know what they can and can't assume about the bindings with
which people will implement their spec.

> > * Is it true that setting a property can never fail? (My opinion: no, it
> >   can fail, and clients must not assume it will succeed)
[...]
> What do most languages do? I would guess that C# throws an exception,
> I think GObject would usually g_return_if_fail() or else silently
> clamp.

Well, obviously "the service crashes" is an unacceptable way to signal
error!

> > * Is it true that all properties must accept *all* correctly-typed values?
> >   (My opinion: no, it can fail, e.g. rejecting non-ASCII strings, or it can
> >   quietly "normalize" values, e.g. forcing strings to lower-case)
> 
> Agreed that few properties actually allow all correctly typed values.

Right. So "good" binding authors must at least provide a way to normalize/clamp
values.

> > * Can specification writers assume ... that that code will be able to cause
> >   failure of Set() with a specified exception?
> I think so (cf. though the comments above about errors)

So, the reason I'm asking this is: in the Telepathy spec (brief
background: abstracting instant messaging by a D-Bus API), I'd like to be
able to say something like:

property MyUserID (s, readwrite)
Must be a valid user ID for the protocol being implemented (e.g. a valid JID
for XMPP). Attempting to set this to an invalid value raises
org.freedesktop.Telepathy.Error.InvalidArgument.

Can I do this, or do I need a read-only MyUserID property and a SetMyUserID()
method if I want those semantics?

> > * Is it true that in the service implementation, readable properties are
> >   always gettable synchronously and with no delay? (My opinion: must be,
> >   otherwise GetAll loses totally - which means Properties are only
> >   suitable for "locally cached" things)
> 
> I would say Get is expected to be fast, but if someone wanted to make
> it slow that would be more an implementation quality issue than a spec
> issue.

I suppose my question is really: Can I, as a specification author, use
properties for something that takes time/round-trips to do, with
services able to process other requests in the meantime? I don't think I
can, and I think this should be a SHOULD NOT in the spec.

GLib and Qt both implement property get/set as synchronous (in the sense
that the service doesn't get a chance to resume its main loop) so I'd
say that this would be a bad thing for a specification author to do,
and that they should use methods instead if they want to be at all
interoperable.

> > * Is it true that in the service implementation, writable properties are
> >   always set synchronously? (My opinion: don't know...)

Same rationale as above.

    Simon
-----BEGIN PGP SIGNATURE-----

iD8DBQFHrFuHWSc8zVUw7HYRAh2xAKC0KQZr0BF0gy9z67D84rb28AJGWgCfbOLv
8Uq7ZpFXq2iU8C/io5AsHnM=
=x3TF
-----END PGP SIGNATURE-----