xcb_take_socket: Document sequence wrap requirements

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@znc.in>
Signed-off-by: Julien Danjou <julien@danjou.info>

diff --git a/src/xcbext.h b/src/xcbext.h
index 2e10ba2..d6366cb 100644 (file)
--- 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);