first cut of hal service description file

[Havoc Pennington]

Hi,

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 ;-)

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.

>  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.

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.

> >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.

> 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.

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.

I think most code works this way anyhow; usually you see:

 if (error == whatever)
   // do thing 1
 else if (error == whatever2)
   // do thing 2
 else
   // do some generic error handler thing, if only rethrow

Havoc