From 6490cc76d3e64342fa34284498e57100d2deda31 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 17 Aug 2010 00:08:29 -0400 Subject: [PATCH] xcb_request_check: improve documentation to better explain implicit sync --- src/xcb.h | 17 ++++++++++++++--- 1 files changed, 14 insertions(+), 3 deletions(-) diff --git a/src/xcb.h b/src/xcb.h index 35d8768..b5feb1d 100644 --- a/src/xcb.h +++ b/src/xcb.h @@ -273,15 +273,26 @@ xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); * @param cookie: The request cookie. * @return The error for the request, or NULL if none can ever arrive. * + * This function collects the error from a void request (one with no + * reply). Because the void request has no reply, xcb_request_check() + * cannot return until either an error occurs, or a subsequent + * non-void request gets a reply. + * * The xcb_void_cookie_t cookie supplied to this function must have resulted * from a call to xcb_[request_name]_checked(). This function will block * until one of two conditions happens. If an error is received, it will be * returned. If a reply to a subsequent request has already arrived, no error * can arrive for this request, so this function will return NULL. * - * Note that this function will perform a sync if needed to ensure that the - * sequence number will advance beyond that provided in cookie; this is a - * convenience to avoid races in determining whether the sync is needed. + * As a convenience, if you call xcb_request_check() without first + * sending a non-void request, xcb_request_check() will send a + * non-void request for you (i.e. it will do a sync, implemented as a + * GetInputFocus request). This implicit non-void request is often + * undesirable because it will result in a blocking round trip inside + * xcb_request_check(). To avoid the round trip, send any request with + * a reply - use GetInputFocus if you have no useful request available + * - and then force that request at the same time you do the + * xcb_request_check(). */ xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie); -- 1.7.0.4