Tutorial notes

[Jeroen T. Vermeulen]

On Sat, August 19, 2006 16:07, Matthew Johnson wrote:

> I've been there and done that. I was trying to use the low-level
> bindings. Have you read my low-level tutorial and Java documentation?

Now that you mention it, I've taken a look at the low-level
tutorial--which is helpful, though of course it can't replace the
conceptual introduction that the main tutorial should provide...  It
hadn't occurred to me at all to look at the Java binding.  Your Java
documentation does seem to do a more organized job of introducing the
basic terms.


>> * Signal
>
> A signal is a DBus message which can be emitted from a program and
> received by any other program which is listening for that type of
> signal.

To pick the last nits, I would say that was the description of a signal
*message*.  That part is also described in the Tutorial.  But it turns out
there is also a relationship between interfaces and signals, and from the
Specification I have since learned that signals are, as far as the object
model is concerned, members similar to methods (but (i) they're one-way
and (ii) they follow a one-to-many communication model without replies).


>> * Proxy
>
> A binding-specific notion of a 'fake' local object which provides the
> same methods as a remote object and when called passes them on to the
> remote object (glib and python experts reply if this is wrong for you)

That's pretty much the conventional explanation for these object/component
systems.  One nagging doubt I have about it is that it seems to stand with
one leg in that world of the component system where an "object" is a
special very specific thing with an unfortunate name, and with another in
the world of OOP where the well-known notion of an object can be used to
explain things.

So maybe what you said about the Java binding earlier is a better way of
saying this as well: proxies are references to objects.  Yes, they present
a direct-call interface for an object that's really remote, but you could
say the same for a Java reference: what you have in your local variable
isn't the object, it's the reference--and yet it's on that that you invoke
the object's methods.  (It becomes more obvious with references in C++,
where a reference may be thought of as a pointer constant, but is accessed
using dot notation).


>> * Bus driver
>
> ???

It's in that first example program:

/* Create a proxy object for the "bus driver" (name
"org.freedesktop.DBus") */

Maybe it's just in there as a joke?  For a newbie it's hard to tell!


>> * Type signature
>
> Again, this is only relevant in some bindings. Each thing which can be
> serialized onto the bus as an argument to a call or signal has a type.

If this sort of detail is really binding-specific, would it make sense to
"turn the tutorial upside down" and start out with, say, the Python
binding?  It would definitely shorten those critical first few examples.

Of course then it would help if the Python binding behaved more like what
you say about the Java binding--perhaps it could support calls like

  dbus.get_object(...).interface.method(arg)

instead of

  dbus.Interface(dbus.get_object(...), interface).method(arg)

Can't go around confronting newbies with such tedious Python verbiage,
especially if they're not familiar with the language!  Besides, why should
the programmer be made aware that a method called "get_object" gets a
proxy object-in-the-python-sense instead of a proper
object-in-the-dbus-sense?


>> As it is, I don't even have a word to set an object in the d-bus sense
>> apart from the other things called object!  At least glib has GObject.
>
> Again, this is very binding-specific. In the low-level bindings of
> course there are no objects. In Java terms they really are just normal
> objects that happen to have implemented a particular interface and been
> exported.

The news that the tutorial does not describe the "native" dbus interface
at all, but merely a more or less arbitrary choice of two higher-level
bindings puts a new light on a lot of my questions.


> I'll leave all this to the glib experts, since I assume that's what it's
> written in. (and having tried to write in the glib bindings, no knowing
> glib, I really don't like them. I assume they are what all good glib
> programmers are used to though).

Well, it's not so much answers for myself that I'm hoping to get here, of
course, as much as changes to the Tutorial!


> No, absolutely be as difficult and picky as you like, it would be really
> good to have this clear by 1.0. Also, when you do understand it, please
> do contribute to the docs.

OK, I'll certainly try.  Thanks for your patience!


Jeroen