[PATCH] xcb_take_socket: Document sequence wrap requirements

[Uli Schlachter]

If lots of requests are send without one causing a reply, xcb can get confused
about the current sequence number of a reply. Document the requirements of an
external socket owner to avoid this problem.

The return_socket callback for xcb_take_socket() originally was supposed to
return the last sequence number used, but the version committed to libxcb never
actually had this signature. This fixes the function's documentation not to
mention this non-existent return value.

Signed-off-by: Uli Schlachter <psychon at znc.in>
---
 src/xcbext.h |   15 +++++++++++----
 1 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/xcbext.h b/src/xcbext.h
index 2e10ba2..d6366cb 100644
--- a/src/xcbext.h
+++ b/src/xcbext.h
@@ -65,15 +65,22 @@ unsigned int xcb_send_request(xcb_connection_t *c, int flags, struct iovec *vect
  * request XCB sent. The caller of xcb_take_socket must supply a
  * callback which XCB can call when it wants the write side of the
  * socket back to make a request. This callback synchronizes with the
- * external socket owner, flushes any output queues if appropriate, and
- * then returns the sequence number of the last request sent over the
- * socket. */
+ * external socket owner and flushes any output queues if appropriate.
+ * If you are sending requests which won't cause a reply, please note the
+ * comment for xcb_writev which explains some sequence number wrap issues.
+ * */
 int xcb_take_socket(xcb_connection_t *c, void (*return_socket)(void *closure), void *closure, int flags, uint64_t *sent);
 
 /* You must own the write-side of the socket (you've called
  * xcb_take_socket, and haven't returned from return_socket yet) to call
  * xcb_writev. Also, the iovec must have at least 1 byte of data in it.
- * */
+ * You have to make sure that xcb can detect sequence number wraps correctly.
+ * This means that the first request you send after xcb_take_socket must cause a
+ * reply (e.g. just insert a GetInputFocus request). After every (1 << 16) - 1
+ * requests without a reply, you have to insert a request which will cause a
+ * reply. You can again use GetInputFocus for this. You do not have to wait for
+ * any of the GetInputFocus replies, but can instead handle them via
+ * xcb_discard_reply(). */
 int xcb_writev(xcb_connection_t *c, struct iovec *vector, int count, uint64_t requests);
 
 
-- 
1.7.2.3


--------------060502060004050505000509
Content-Type: application/octet-stream;
 name="0001-xcb_take_socket-Document-sequence-wrap-requirements.patch.sig"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
 filename*0="0001-xcb_take_socket-Document-sequence-wrap-requirements.pat";
 filename*1="ch.sig"

iQEcBAABCAAGBQJM8N2DAAoJECLkKOvLj8sGjnwH/i/LxB3nUqjY5ATZ04pYEegNglur5scx
C41hluEHIq3AjTmzyGo3IqJJSOHbMn2d8HJm9WgwJtTSpfmvBZHR4mMpBba43a74OKFQUFzA
NMSudo/Ufe4lhN5x5aoryvHElSrmapzsS1wtEp3uQSnXS8O0hXBkqJOGa8lghRTPI6dp/7SV
q2Cu+0YjmaXVz3YATusJsaUVpT5f1OIEVHmDFpXVWcYn9/slxP9+LiNCE/rLg1meiUMAhnRu
WK9rdgSF2nwGC8r17z1YSXjli4D0/t4velLfzYGZhky2v0QaiHjB+UzCwMvoK2df2f9YLHOs
Wcy+RTwNMmG3viVP/L9yuIg=
--------------060502060004050505000509--