Attachment 37905 Details for Bug 29599 – improve xcb_request_check docs

[patch] improve xcb_request_check docs

xcb_request_check-improve-documentation-to-better-ex.patch (text/plain), 2.11 KB, created by Havoc Pennington on 2010-08-16 21:11:02 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Havoc Pennington

Created: 2010-08-16 21:11:02 UTC

Size: 2.11 KB

patch

obsolete

>From 6490cc76d3e64342fa34284498e57100d2deda31 Mon Sep 17 00:00:00 2001
>From: Havoc Pennington <hp@pobox.com>
>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
>

Actions: View | Splinter Review

Attachments on bug 29599: 37905 | 38126

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.