[Xcb] XCB error handling; my penultimate proposal

[Jamey Sharp]

On Sun, Dec 18, 2005 at 09:32:22AM -0800, Barton C Massey wrote:
> Of course, my favorite is alternative 3: "let's do both!"
> 
>    3. Provide fooErr() and foo() versions of all *requests*
>       expecting replies. If an application uses fooErr(), it
>       *must* supply a pointer to storage in the extra
>       argument to *Reply() (or XCB will dump core on an
>       assertion).  This request will behave as in (1).
>       If it uses foo(), it *must* give 0 in the extra
>       argument to *Reply() (or XCB will dump core on an
>       assertion).  This request will behave as in (2).

I'd modify this proposal to pass the XCBGenericError** to fooErr, rather
than fooReply, because that eliminates the need for these asserts. In
that sense this is an API extension to my proposal, #2.

And I don't think there's any reason to abbreviate here: it may as well
be called fooError.

>       Further, provide fooErr() versions of requests
>       *not* expecting replies.  Provide a function
> 
>         int XCBCheckErr(XCBConnection *c,
> 	                int seqnum,
>                         XCBGenericError **e)
> 	
>       that may only be called with the seqnum of such a
>       request, and *must* be supplied with a pointer to
>       storage in the third argument.

Again I would drop the third argument in favor of passing it to fooErr;
but this means that CheckErr is just the function that blocks until the
outcome of a request is known. I keep forgetting that there's been some
demand for that function.

If CheckErr stayed in the above form, the second argument should be an
XCBVoidCookie so the type system will enforce that it can only be called
for void requests.

>       (Perhaps further require that the second argument to
>       XCBSync() always be 0, or eliminate it, or make it
>       return only the error from the noop used to do the
>       XCBSync() by using the *Err() request if the pointer
>       is supplied?  I'm not sure what its intended purpose
>       is currently.)

I suppose it's never useful to suppress errors from a Sync. It just
seemed natural not to hide the error argument that's inside the calls
the Sync function is doing.

> 3 is kind of complicated, but it has some putative
> advantages.  3 allows one to dump core whenever an error is
> received by WaitForEvent() while still allowing suppression
> of "expected" errors even for requests not expecting
> replies.  3 doesn't modify the existing API in any important
> way---the only change is that code that tried to use the
> error field of *Reply() will have to be modified to either
> use the *Err() requests or to stop doing that.  For much of
> this code that was a good idea anyway, since the results of
> doing what it was doing are unpredictable.
> 
> What do folks think?

I like #3, given the above changes. I strongly dislike leaving the
XCBGenericError** argument in the *Reply functions unless it's in the
style of Keith's proposal, #1 -- which I'm not a big fan of due to the
asymmetry.

Correct me if I'm wrong, Bart: you feel at this point it's too late to
make backwards-incompatible changes that affect most of the code that
uses XCB. I disagree, and I really want a clean API -- enough to
inconvenience the good people who have been kind enough to test out and
improve this code for us. I think they will forgive me, but I'd be happy
to make the necessary changes to their source by hand myself if that's
what it takes to release with a satisfying API.

--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20051219/488823ce/attachment.pgp