[Xcb] XCB error handling; my penultimate proposal

[Jamey Sharp]

On Mon, Dec 19, 2005 at 12:59:45PM -0800, Barton C Massey wrote:
> (As for the XSync() thing, I suspect that it makes sense to
> provide XSync() and XSyncErr(), where the *Err() is the one
> returned by the noop itself?)

If GetInputFocus returns an error, something is wildly wrong, and you'll
probably find out about it soon enough some other way. The reference
server implementation has no error returns for that request, AFAICT.

> The two reasons I prefer 3 over 5 are: (a) while I agree
> that if we're going to change the API we should do it sooner
> rather than later, I don't think this change in semantics is
> a sufficient reason to change it

We can debate "sufficiency" forever, I suppose.

> (b) you're now
> supplying a pointer to the library that is set aside and
> filled in "later".
> 
> Other libraries tend not to do that, because it is
> error-prone and difficult to work with.  Note, for example,
> that if the storage to receive the error is allocated by the
> caller, this storage must remain valid until the cookie is
> forced, which means that a local can't be used if the cookie
> is not forced in the dynamic scope of the request.
> Conversely, if it's allocated by the library, it must then
> be disposed of by the caller, which is going to lead to
> memory leaks.
> 
> The imputed advantage of 5 over 3 is that folks using 3
> screw up and have the app dump core.  But I can live with
> this by comparison---it's easy to find and fix.

If you don't want to change the XCB*Reply interface, then plan 3 has at
least part of the same problem: XCB currently mallocs the error
structure and then hands the new memory back to the caller. Plan 5 at
least could allow for efficiently using a client-allocated buffer.

But I see your point. I'm not convinced yet that it's the wrong choice
given that we're coding in C, but I do see it's not ideal.

Let me throw Plan 6 out there:

	Like Plan 3, XCBFoo and XCBFooError have identical signatures.
	Like Plan 5, XCBFooReply takes two arguments -- but if the
	cookie was created with XCBFooError, the returned value may be a
	XCB-allocated, caller-freed pointer to either a reply or an
	error; the caller distinguishes between the two cases by testing
	whether rep->response_type is 0 (error) or 1 (reply).

This has the interesting property that it's always correct to write code
to handle the case that you got an error instead of a reply, and always
correct to free the value returned by XCBFooReply. Generic code, like
xcb_reply, can be written to handle errors regardless of whether its
callers pass in cookies from the XCBFooError functions. I suppose that
can be achieved with a small change to Plan 3 as well.

On the other hand, Plan 6 has this problem: If code written under the
assumption that it will never get an "errorable" cookie is called with
one, it may process an error as though it were a reply, which can
include reading garbage data and accessing outside of allocated memory.

> Right now, I guess I'd vote
>    best = 3 > 5 > 4 > 2 > 1 > 0 = worst
> where 0 is to leave things as they are.

I'm not sure how I'd vote at this point, except that Plan 0 is clearly
intolerable.

I've bought into the idea of being able to get the error when asking for
the reply, but I guess I'd still choose to sacrifice it (Plan 2) if we
can't work out how to do it cleanly. Plan 2 gives a clean base to build
the other plans on top of, as API extensions or as separate libraries.

>     (b) Occasionally, I'll make a request that I know might
>         fail, and want to handle the expected failure or
>         shutdown otherwise.  For example, I might choose to
>         try to read a property off the display knowing it
>         might not be there.  In this case, it is quite
>         convenient to be able to ask to see any error that
>         is returned for the request.

In that example you probably don't care what error occurred, and just
want to know whether you successfully got the value of the property and
not call your usual error handler. Gdk on X does this *a lot*.

> Right now, simple Xlib apps either do (a) or just ignore
> errors altogether.  Scanning over xcb-demo:

Yes, at the moment the XCB demos are not good examples of error
handling. If anything goes wrong in most of them, it's near impossible
to debug.

> What do toolkits etc do now?

I already quoted three instances of Gdk using its error handler stack to
examine the errors returned by particular requests. What more are you
looking for?

--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/039e829c/attachment.pgp