Message-based API vs signal/method-based API (Was Re: GDBus/GVariant plans for next GLib release)

[David Zeuthen <david fubar dk>]

On Thu, 2009-10-15 at 10:54 -0400, Ryan Lortie wrote:
> >    The API does not expose a GDBusMessage type since that would cause
> >    unwanted API that would assist in using the API as a whole in a
> >    wrong way (e.g. exposing on-wire details like message headers
> >    can be nasty). Instead, the API is based on invoking/handling methods
> >    and receiving/emitting signals.
> 
> I think we might want to have some sort of GDBusMessage class.  Here are
> a couple of reasons why:

It's not that message-based APIs is better than signal/method-based APIs
or the other way around - it's just deciding what level of abstraction
we want our APIs to have. My view is that signal/method-based APIs will
cover 99.9% of all cases and that providing a message based API will
make things, say, 10% harder to use for everyone. I don't think that's a
good trade-off.

(I just pulled 95% of these statistics out of my ass)

> 
>  - I think it is valuable to be able to register very low-level filter
>    functions (or signal watches, or async reply handlers) that deal
>    directly with the message as it came off the bus (including the body
>    and the full set of headers).

If people want this very low-level functionality, they can always use
libdbus-1 or speak directly to the socket - do you have any specific
examples where the proposed method/signal-based API wouldn't work?

>  - This is useful for people who want to do other types of object
>    binding on top of GDBus.

Any specific examples?

>  - Maybe you don't want automatic GError conversion

With the way things work now, you are guaranteed to _always_ be able to
recover the full D-Bus error in its pristine form from the GError (using
g_dbus_error_get_dbus_error_name() and g_dbus_error_strip_error())

>  - Easy way to send a reply to a specific message
> 
>  - No need to pass many arguments to functions or to have the types of
>    arguments varied by the sort of function (incoming method call vs.
>    signal vs. async result, etc...)

Any specific examples for these two points?

> This could be approximated with a GHashTable or GVariant dictionary (of
> headers) and a GVariant (for the body).  Our GDBusMessage class, in
> fact, could be little more than a wrapper around the two.

Keep in mind that we can always add the GDBusMessage class later if it
turns out we really want it. I'm mostly against doing this because it
means exposing a lot of API and some overhead as well.

Thanks,
David