Bug 6120

I put that there, regarding the documentation (copied from Jamey on mailing list). Has anyone written 
some code to see whether XCBGetRequestRead works as advertised?

Jamey wrote:

The only thing this function is useful/intended for is to check whether
forcing a particular reply cookie would block. Xlib uses it that way,
and my xcb_reply library uses it that way. It's not used by any other
code, as far as I know.

This function doesn't fit the use case for several reasons. It's not
thread-safe, though Josh complained that apps just shouldn't do this
across multiple threads. It's error-prone -- all two calls in current
code are buggy -- because callers have to check if one sequence number
is less than another, and that gets hard at 32-bit wrap. And it answers
the wrong question: it can prove that a call won't block, but it might
incorrectly tell the caller that a call will block when it won't.

Since that's all it's useful for, I think we need a non-blocking variant
of XCBWaitForReply, instead. We already have a non-blocking variant of
XCBWaitForEvent. There are several things that make this complicated
though.

1) Type-safety. XCB*ForEvent uses a generic event pointer type.
XCBWaitForReply uses a void*, but appears only in the extension API and
is intended to be called only by a type-safe wrapper. Simply duplicating
the function in a Poll variant suggests we ought to duplicate all the
type-safe wrappers as well. Obviously we *can* do this, but should we?
On the bright side it only affects requests that have replies, and those
are rarer than the other kind.

2) Return value. We might detect three distinct conditions, and the
caller needs to be able to tell the difference. These are: returned a
reply because one was immediately available; returned nothing because we
would have had to block to return a reply; returned nothing because we
can prove no more responses can come to that sequence number.
XCBWaitForReply only blocks in the second case.

3) Interaction with X error handling. Probably this new function needs
to poll for "either reply or, if requested when enqueueing, error", as
per plan 7.

OK, it's been reviewed, deemed wanting, deprecated, and replaced. Closing the bug.