first cut of hal service description file

[David Zeuthen]

On Thu, 2005-03-31 at 00:57 -0500, Havoc Pennington wrote:
>  - Only one language of interest actually has the throws in the method 
>    signature (Java).
> 
>  - because of that, reflection-based bindings (generating introspection
>    data from the language introspection features) will never get the 
>    throws info right.
> 
>  - all D-BUS methods can throw exceptions, because IPC is involved.
>  
>  - You can get security and other exceptions from the bus itself, and I 
>    want to be able to add more of those over time, and exceptions   
>    specific to particular transports (e.g. if you tunneled over X11 
>    protocol, you might have associated exceptions). So at the very 
>    least, bindings should always have a "DBusException" that 
>    would be used for all these errors from the bus so it doesn't change
>    method signatures if we add new errors.
> 
>  - Real-life code almost always special-cases one or two specific 
>    exceptions, then has a fallback case for "any other exception"
> 
>  - Because most languages don't enforce type safety here, I really 
>    doubt the exception info in manually-maintained introspection
>    files will ever be accurate.
> 
>  - this is just plain complicated and doesn't add corresponding value.
> 
> >    I just added comments about what hald can throw at you today.
> 
> This is the right approach I think.

Well, doesn't this sort of come down to what the authoritative service
description is? The code or the IDL. Chicken and egg, isn't it?

If it's the code, then sure, it's difficult (stopping problem) to figure
out via introspection and the XML exported degrades (in the worst case)
to just saying a given method always casts DBusException (which, in any
language/runtime, is the base class for all exceptions to be thrown).
It's still correct code, but it's suboptimal. Oh, and the code itself
may hint the proxy that the Lock() method may throw the AlreadyLocked
expection (either runtime or compile time).

However, if the IDL is the authoritative service description, the
programmer can actually annotate it, like saying Lock() may throw
AlreadyLocked in addition to DBusException. Surely, the programmer using
the IDL that wants to Lock() is only interested in handling
AlreadyLocked in a special way, exceptions not of that class (like bus,
network and security exception) is handled in the generic way. 

It's not so much so the generated Java will force me to handle the
exception to compile, it's equally much so documentation and IDE's, like
Eclipse, can hint me, at development time, that the Foo() method may
throw this particular exception in addition to the generic
DBusException. I think that is useful.

In particular, if we include what exceptions to throw in the IDL, the
generated introspection code should carry that onwards such that
myfile.xml == Introspect(GenerateCode(myfile.xml)) modulo comments of
course.

So, I think what I'm getting at, is that it's indeed useful to include
what exceptions apart from DBusException a method may throw in the XML
(whether it's hand-written or generated from introspection data). Does
that make sense?

[snipped bunch of other useful comments I don't object to]

Cheers,
David
 









 

> 
> >  - As noted for objects implementing the org.freedesktop.Hal.Device
> >    interface, there is no way to know a'priori what objects these are
> >    except perhaps that they reside in a certain name space. 
> 
> The object path should only be in the XML format when it's being used to
> introspect live objects probably. If you're using this as "IDL" then it
> doesn't need object paths. I don't think we're ready to use it as IDL
> yet other than as a way to write specs - we haven't defined where to
> install files or anything of that nature.
> 
> >    Any chance we can have some kind of proxy manager so it becomes
> >    even easier to write client code? Ideally, I'd like to be able
> >    to just pass the object_path to the generated function...
> 
> I think there's some historical discussion of this pretty far back in
> the archives. I don't remember any details of it though and I could be
> wrong.
> 
> Off the cuff, I wouldn't do a proxy manager for this; the main purpose
> of the proxy is just to save typing in the interface/path/etc. over and
> over and have an object to connect signal handlers to. But if you're
> only invoking one function, and the interface/path/etc. are hardcoded in
> that function, the proxy serves no purpose. Just generate code like:
> 
>  void generated_function (const char *path, int arg1) {
>   call_method ("my.bus.Name", "my.Interface", path, DBUS_TYPE_INT32,
> arg1, DBUS_TYPE_INVALID);
> }
> 
> >  - Where am I supposed to ship the hald.xml (and should it be named
> >    hald.xml) at all? 
> 
> Not defined at all yet.
> 
> >    - do we expect certain languages/runtimes to load the hald.xml
> >      file at runtime to generate proxies on the fly? (Java, Mono
> >      comes to mind). If yes, we need to ship it with the runtime
> >      package (hal.rpm)
> 
> IMO generating proxies on the fly should be done by calling Introspect()
> on the remote object, rather than by loading files.
> 
> >    - do we expect certain languages/runtimes to consume the hald.xml
> >      file at build time? (glib comes mind)
> 
> Well it's sort of necessary for C/C++, unless we make people just use
> varargs (which is not IMO totally crazy, but I understand people may
> find it annoying). Personally in my apps I think I'd tend to just use
> varargs and the proxy object directly but I find it hard to explain why
> that "feels right" to me.
> 
> >    I suppose the answer to these questions are both yes.
> 
> I think it's no to the first, yes to the second. In other words I'd put
> the xml files in -devel
> 
> We should most likely call them something other than .xml also... some
> extension specific to what they are.
> 
> One of the general themes I'm getting to here is that I think the .xml
> files should be optional; if you want to just write a cheesy app in
> python without any "IDL" file then you should be able to do that. You'll
> make life a little annoying for C programmers, but if someone complains
> the IDL can be added later.
> 
> >  - To deploy the hal service in a message bus scenario, I still need to
> >    write a policy file; would be crack to generate this from the service
> >    description file using annotations?
> 
> You mean from the "IDL" file or the .service file?
> 
> I'm not sure I see how to do this generically, but a simple custom
> script to do it for HAL makes plenty of sense. This would be one of the
> benefits of using XML for the IDL file (you can easily write your script
> in whatever language)
> 
> >  - I've used the term 'service description file' throughout this email
> >    as I wasn't really sure what it's called :-) - we probably need a
> >    glossary before 1.0 (if we don't have one already).
> 
> There is one at the end of the spec, just extend it ;-)
> 
> Havoc
> 
>