[Xcb] XCB error handling; my penultimate proposal

[Barton C Massey]

Jamey, Keithp and I talked a lot last night about XCB error
handling.  After thinking about it a bit, here's what I
*think* I want.  Comments are welcome.

The problems: The current XCB error handling is kind of a
disaster.  All the *Reply() functions have an extra argument
that can hold a pointer to an error structure; if so, and
there's an error, that structure gets filled in by the
error, *and the error is removed from the stream* so that
WaitForEvent() and friends won't see it...unless they've
*already* seen it, in which case they've consumed it and it
won't be filled in.  Uggh.

There are several design alternatives:

   1. *Never* return errors for requests expecting replies
      to WaitForEvent(); if the app wants these errors, it
      *has* to use the extra argument to *Reply() [Keithp]

   2. Elide or ignore the extra argument to *Reply().  Apps
      should process all errors in WaitForEvent(). [Jamey]

1 makes it easy to supress "expected errors", and makes the
reply checking code easy to write, but it's a pain in the
neck for apps that want to do clever things or just dump
core on *any* error.  2 has the opposite properties.

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

      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.

      (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.)
      
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?

    Bart