[Xcb-commit] src

[Julien Danjou]

 src/xcbext.h |   15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

New commits:
commit 8ecd754b168a0352783bf1ba0f0887f7ff479ee8
Author: Uli Schlachter <psychon at znc.in>
Date:   Wed Nov 17 20:26:11 2010 +0100

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

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);