[Xcb] XCB error handling; my ultimate proposal

[Barton C Massey]

After some more thought, here's the only proposal I'll be
happy with: Plan 7. :-) Plan 7 is a variant of my previous
"make everyone happy plan" that will make me happy, I think
will make Jamey happy enough, and I think will make Keithp
happy enough; no one else has expressed a strong opinion
that I have seen. Plan 7 will also cause very minimal
disruption to existing code both inside XCB and elsewhere;
essentially, XCB clients will only have to be fixed where
they are currently broken anyhow.

  For every request expecting a reply:
    Provide a *RequestBlind() version of the request that
    defers errors to the event queue.  Retain the
    two-argument *Reply() function.  For *Request(), if the
    second argument is not a 0 pointer, it is filled in with
    the error record.  Otherwise, the error record is
    discarded.  For *RequestBlind(), the second argument to
    *Reply() must be a 0 pointer (else an assertion
    failure), and any error records are put in the event
    queue.

  For every request not expecting a reply:
    Provide a *RequestChecked() version of the request that
    keeps errors out of the event queue.  If a
    *RequestChecked() was issued (and returned a non-zero
    sequence number), the application is responsible for
    calling
      XCBGenericError *XCBRequestCheck(XCBVoidCookie c)
    at some point; this will sync the connection up to the
    given sequence number and return 0 if the request
    succeeded else a pointer to the error, which will not
    appear in the event queue.  Failure to call
    XCBRequestCheck() when needed is essentially a memory
    leak.  For the unchecked *Request(), any error will
    appear in the event queue, and a call to
    XCBRequestCheck() will cause an assertion failure.

I can imagine Keithp objecting that for now we shouldn't
code such a complex scheme until we need it, and instead
should just do the part that doesn't let errors into the
event queue for now.  However, some of the XCB demos really
want to just exit on any error, and for the ones that
actually read the event queue this mechanism is perfect.
Further, I really want to code my upcoming toolkit (yes, I'm
gonna do it) in the style that lets most errors cause an
exit in the event handler but catches "expected" errors
inline.  Plan 7 lets me do this.

I can imagine Jamey objecting that the second argument to
*Reply() is still an affront to god and man, and should be
elided now while we have the chance.  However, it is
sometimes quite convenient to both keep an error out of the
event queue and discard it unexamined; the current xcb-demo
code sometimes does this.  The two-argument *Reply() makes
this quite easy, and is harmless otherwise IMHO.

Further, Plan 7 really acts just like the existing error
handling except in the case where the app expected the error
from a request expecting a reply to be delivered to the
event queue or to the *Reply() function, neither of which
would happen reliably anyhow in the current scheme.  This is
not a huge deal, since apps should be checking for the null
pointer return from *Reply() and reacting appropriately
anyhow.  I think most of the xcb-demo code will actually
work *better* unmodified under Plan 7 than it does under the
current scheme.

Note that, unlike my *penultimate* proposal (Plan 1) this is
my *ultimate* proposal. :-) At this point, I'm out of
proposaling.  I can help implement this if we decide to go
this route, but I suspect it's mostly going to be Jamey's
job.  I'm sure Jamey and Keithp would welcome comments on
Plan 7 or any of the others by outside folks.

	Bart