[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


--------------010105080808010802050509
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"

iQEcBAABCAAGBQJM5C5UAAoJECLkKOvLj8sGxw0H/2GNPciceYmnk7rDYu6ZuUDHQEBuzeU7
uHym73DXw2lh2TEZQJNBO2HHbStP/GrECF+KkRwImzm82i48wJgoiA39uT6nPXkxt5j5XNMT
c4T+R5ButqO+MIz4cP3KcuPheBVKwfS2I/0C2JKvCLRaPXB98mut+xPVR2pqNDqHTSGrXX+Q
fIkNk5/EnJF6kmY0p6AOhhXKk9/afBTx5c9B/2mLq9u1CmEUMmVohVLWaKtdFB6gYrp74JDd
Z4nbCmPySEWgYVWgwiN3QlxEqcqBqnF5hp9KGh7EyRHO9XRU+KCy0CDAHhmIKCpwt6fA94F7
BFdh3GBENFJU19NRCaxH+E8=
--------------010105080808010802050509--