Errors and the introspection format

[Thiago Macieira]

Havoc Pennington wrote:
>Possibly the NoReply annotation should have been GLib.NoReply, and
>separately we should have a Qt.Async to match the DCOP-compat kind of
>feature done in Qt bindings which is slightly different; this would also
>help clarify that NoReply is just about bindings and code generation,
>not about any intrinsic property of an interface or the wire protocol.

No, they're the same thing.

As I explained in the other email, the term "async" is being abused 
for "no-reply" because of DCOP compaibility (i.e., old misnomer). It 
means "the function will still be executing while control has returned to 
you". It's not an asynchronous call in the sense of DBusPendingCall 
callbacks -- which, in the original Qt binding implementation, was 
sendWithReplyAsync.

But, as you suggested, here are a few use-cases to clarify:

* LaunchMusicPlayer:
I'd say this is a normal call. While the music player will take some time 
to load, you want to know whether the launching was successful. So this 
method would be have one output argument indicating success.

* CalculatePI:
Again, normal call. This would be a really slow call, so its return value 
will take some time to happen. Since this is really exceptional, the 
caller should know what it is doing, set the timeouts higher and place an 
asynchronous (DBusPendingCall) call, so that it'll get the reply 
hopefully sometime before the next century.

* ReloadConfiguration: (a.k.a. SIGHUP)
You just want to make it reload the configuration: there's no success or 
not. This would be a candidate for the NoReply annotation.

When a caller tries to place a call to this function, it should see the 
annotation and SHOULD use "fire-and-forget" (DCOP "async") mode.

If the caller did not set the noreply flag in the call message, the callee 
MUST return a reply. In this case, it'll be an empty success reply every 
time if the method was called, or an error if it couldn't.

* DownloadFile:
Like CalculatePI, this is a lengthy operation. However, given the number 
of possible different outcomes and given the fact that the application 
will probably want to show some progress bars, estimated time and 
possibly even start to render the file while its download in progress, 
I'd say this is a real asynchronous function with special circumstances: 
all the replies will be handled through Method "Callbacks" back to the 
user application. It should return ASAP a handle indicating the context, 
which will be used all the callbacks. But the real download will start 
later and you won't know if the _download_ succeeded until much later.

So, I'd say the input parameters for a DownloadFile function would be the 
URL of the file to download and the service + path of the callback object 
(interface and methods would be standardised elsewhere). We'd have 
methods like "Data" for data being received, "MetaData" to receive (for 
instance) headers, "Finished" to signal completion or "Error" if 
something weird happens.

-- 
Thiago José Macieira - thiago.macieira AT trolltech.com
Trolltech AS - Sandakerveien 116, NO-0402 Oslo, Norway
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060221/c539879f/attachment.pgp