[Xcb] ApiFct, ApiFctChecked and ApiFctUnchecked

[Barton C Massey]

OK, here's the brief outline---hopefully this will provide
someone with the start of documentation for this...

There are essentially two modes of error handling in Xlib.
In one model, when a server-side error occurs the resulting error
is queued in the event queue for later retrieval.  (There
are various hooks that can modify this behavior.)  In the
other model, when a request expecting a reply fails on the
server side, an abnormal return from Xlib occurs and the
Xlib client can then figure out what to do.  For obvious
reasons, let us call these "asynchronous" and "synchronous"
error processing.  Note that client-side Xlib errors,
e.g. out-of-memory, are not consistently handled by either
mechanism.

XCB never had a clear error model, but to the extent there
was one it mirrored the Xlib behavior.  Now, with Plan 7,
clients can choose between the asynchronous and synchronous
model on a per-request basis.  This is what's behind the
notion of Checked and Unchecked requests.  Let us call
requests that end with neither Checked nor Unchecked
"normal" requests.

XCB synchronous mode:

  When calling a request expecting a reply, use the normal
  request.  A client-side error will be indicated by
  returning a cookie containing a sequence number of 0 (this
  number being reserved for XCB errors through Jedi mind
  tricks).  Otherwise, if forcing the reply cookie results
  in a null pointer, a server-side error has occurred.
  Supplying a pointer to an error record to the Reply()
  function will allow XCB to fill in the details about the
  error. 

  When calling a request not expecting a reply, use the
  Checked variant, which will return a VoidCookie.  As
  before, a client-side error will be indicated by a zero
  sequence number.  When you want to find out whether a
  server-side error has occurred, use XCBRequestCheck(); but
  note that this may cause a round trip to ensure that any
  error has been returned from the server.

XCB asynchronous mode:

  When calling a request expecting a reply, use the
  Unchecked variant.  Supply a 0 as the error pointer in the
  corresponding Reply function.  As usual, any client-side
  errors will be indicated by zero sequence numbers or null
  pointers.  Server-side errors will be enqueued in the
  event queue for later retrieval during XCBWaitForEvent()
  or XCBPollForEvent().

  When calling a request not expecting a reply, use the
  normal variant. As usual, any client-side errors will be
  indicated by zero sequence numbers or null pointers.
  Server-side errors will be enqueued in the event queue for
  later retrieval during XCBWaitForEvent() or
  XCBPollForEvent().

For writing standalone applications, the synchronous-mode
stuff is nice: it also allows for direct error-checking in
tight code.  Toolkits may want to use the asynchronous mode,
which treats "all errors as equal".  Synchronous mode and
asynchronous mode can be selected on a per-request basis, so
mix and match.

Hope this helps!

	Bart

In message <Pine.LNX.4.64.0608141037280.1802 at grozny.maths.univ-evry.fr> you wrote:
> 
> 
> On Sun, 13 Aug 2006, Barton C Massey wrote:
> 
> > The XCB API documentation on the wiki page explains them, I
> > think.   Search for Checked and Unchecked in the Protocol
> > Stub API
> >  http://xcb.freedesktop.org/wiki/ProtocolStubApi#head-532f87594d97c68c4bb55014a5add756425a2c07
> > (uggh) and let us know if you have questions.
> 
> ha, right. Thank you. Well, I would also like a simple example on how to 
> use these functions and the error system. At least to include it in the 
> tutorial. I want to use it for evas and ecore.
> 
> Vincent
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb