first cut of hal service description file

[David Zeuthen]

On Thu, 2005-03-31 at 18:49 -0500, Havoc Pennington wrote: 
> Maybe an important point that's lost here is that for every language but
> C, the bindings are intended to work by doing:
> 
>  SomeRandomObject o = new SomeRandomObject();
>  connection.registerObject(path, o);
> 
> Here the object is introspected and exported remotely. Now, if the
> object is in Python or C# or whatever, we have no idea what exceptions
> any of the methods throw. So we just _can't_ guarantee that the
> introspection XML has this data, unless we force an API like this:
> 
>  SomeRandomObject o = new SomeRandomObject();
>  connection.registerObject(path, o);
>  connection.addExceptionToObject(o, "MyMethod", "WhateverException");
>  connection.addExceptionToObject(o, "MyMethod2",
> "WhateverElseException");
> 
> and that just plain old blows, in my opinion ;-)

Well, given that the design goals of D-BUS is intra-desktop-session-IPC
and system-desktop-IPC we don't really want too many different API's
which means we'll have a limited set of applications providing D-BUS
services. 

I'll agree that it blows for generic IPC mechanisms though. But, hey,
you're saying yourself this isn't the goal for D-BUS :-)

> In other words the "CORBA way" (writing IDL and generating code from it)
> is _not_ intended to be the normal mode of operation, just the legacy
> "C/C++ sucks" mode of operation.

Yeah, but you only covered the server side bits above. I do believe we
want to generate client-side code from the introspection bits, to
leverage the power of type-safety where available, yes?

> 
> >  If you factor in that D-BUS services will need
> > to provide stable ABI's in order to be useful, this is something that
> > will get fixed eventually.
> 
> But the argument I'm making is: don't put the exact exceptions thrown in
> the ABI contract. Then we won't break ABI as this changes.

The only entity breaking the ABI is the application implementing it;
e.g. Rhythmbox v42 might not fully implement the
org.freedesktop.MusicPlayer interface because it doesn't throw the
QueueDoesNotExist exception when for the queueSong(DocumentMusic song)
method. That can be fixed in Rhythmbox v43 though.

Note here that I'm not talking about requiring D-BUS bus or runtime to
give such assurances; they can just declare that they throw the
superclass of all exceptions (DBusException) and the caller need to
investigate. 

This is not much different from Java, e.g. the 

class List {
   void getElement (int i) throws Exception;
};

is as good as

class List {
   void getElement (int i) throws IndexOutOfBoundsException;
};

only it's less expressive. It sort of blows to be an application in
the first case because now you need to go to a website / read a PDF
about exactly what exception List::getElement throws.

> I don't think my suggestion is very radical, since it's what every
> widely used programming language except Java does. I personally _prefer_
> what Java does, but at the same time, I don't think D-BUS is the place
> to set the rules. Most languages do not put exceptions thrown in the
> type signature of the method.

Yeah, I'm aware of that.

> > >From a practical point of view I think developers don't really care
> > about handling exceptions from the bus; they'll just abort() because
> > these are very exceptional conditions that apps really shouldn't care
> > about. Do you disagree?
> 
> I do, I think it's necessary to handle "network communications"
> exceptions. If the app at the other end of your conversation crashes,
> you'll get an exception, for example. Or if using TCP, it could time
> out.
> 
> This is hard to deal with, but it's kind of inherent in network
> programming.

Well, today in 2005, most software don't get this right; I wish it did,
but it doesn't. 

My point was really that desktop level applications consuming things
like D-BUS API's are not likely to get this right anyway, like it or
not. You can't expect desktop level software to reconnect to a service,
if it goes down; it's just not going to happen. 

Rather the fix is that the service shouldn't go down in the first place.
This is sort of similar to the "never restart D-BUS daemon thread".

Similarly, the only program that I know who can handle losing the X
connection is XEmacs and I consider this feature crazy.

> > What I do think developers care about, or rather should care about, is
> > handling application-specific exceptions such DeviceAlreadyLocked,
> > CannotAcquireScreensaverMutex, NotificationAlreadyShowing and so forth.
> 
> And I would say they also need the "catch (...)" wildcard case and treat
> it as a network failure.

Sure, but what I said above is that most of these guys are going to do
abort() instead. They shouldn't, but they will :-)

> Basically I think the ABI contract should be:
>  - if the thing fails due to NotificationAlreadyShowing, that exception
>    will be thrown
>  - AND any appropriate exception can be thrown if something else goes 
>    wrong
> 
> In other words, we may guarantee in the ABI that a certain situation
> results in a certain exception, but there's no ABI guarantee that only a
> particular set of exceptions will be thrown.

Exactly what I asked for. So, I'd like to get hal to return this piece
of introspection data

    <method name="Lock">
      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="hal_device_lock"/>
      <arg type="s" name="reason" direction="in" />
      <arg type="b" direction="out" />
      <throws name="org.freedesktop.Hal.NoSuchDevice" />
      <throws name="org.freedesktop.Hal.PermissionDenied" />
      <throws name="org.freedesktop.Hal.AlreadyLocked" />
    </method>

and for Java this might give the following generated client code

 package org.freedesktop.Hal

 interface Device {
   boolean Lock (String reason) throws NoSuchDevice, PermissionDenied,
                                       AlreadyLocked, DBusException;
 };

Now, this is useful in other scenarios as well. First of all, app
developers like me can convey to all developers wanting to use hal what
app level exceptions that hal might throw in the place where they'll be
looking for it - the introspection data. They don't need to find the
spec which is likely to be out of date too :-)

Second, which is more blue sky (but we should aim high), you can build
this into IDE's, e.g. MonoDevelop, Eclipse or whatever could hint the
app developer that she should handle these exceptions.

Will you take a patch against the spec for this?

Cheers,
David