[Xcb] [PATCH 6/8] Add event queue splitting

[Uli Schlachter]

Hi again,

just to make sure that I understood this API correctly, let me try to write some
documentation:

On 07.11.2013 11:14, Uli Schlachter wrote:
> On 07.11.2013 04:45, Keith Packard wrote:
[...]
>> +/**
>> + * @brief Returns the next event from a special queue
>> + */
>> +xcb_generic_event_t *xcb_poll_for_special_event(xcb_connection_t *c,
>> +                                                xcb_special_event_t *se);
>> + 
>> +/**
>> + * @brief Returns the next event from a special queue, blocking until one arrives
>> + */
>> +xcb_generic_event_t *xcb_wait_for_special_event(xcb_connection_t *c,
>> +                                                xcb_special_event_t *se);
>> + 
>> +/**
>> + * @brief Listen for a special event
>> + */

Listen for a special event. Any events matching these conditions will be
filtered out of the normal event stream and be available only through
xcb_poll_for_special_event() and xcb_wait_for_special_event().
@param c The xcb connection.
@param extension The major number of the extension that generates this event.
@param eid The event type of the GE event that should be filtered
@param stamp A variable that will be incremented every time that a new event is
received. This update will only be protected internally to libxcb. This means
that you should never modify this value directly and may only read it
atomically. This argument may be NULL in which case no increments are performed.
@return A handle to the filter that this function installed or NULL. This must
be destroyed via xcb_unregister_for_special_event().

Having written the above, I wonder if the first argument should be a struct
xcb_extension_t instead of a major number. I think that this would be the first
function to use a major number like this and it is trivial for the
implementation to turn the xcb_extension_t into a major number.

>> +xcb_special_event_t *xcb_register_for_special_xge(xcb_connection_t *c,
>> +                                                  uint8_t extension,
>> +                                                  uint32_t eid,
>> +                                                  uint32_t *stamp);
>> +
>> +/**
>> + * @brief Stop listening for a special event
>> + */
>> +void xcb_unregister_for_special_event(xcb_connection_t *c,
>> +                                      xcb_special_event_t *se);
[...]

Oh and: Could you please add if(!se) return; to this function? This could
simplify the error handling of library users.

With this change applied:

Stop listening for a special event. This undoes the effect of
xcb_register_for_special_xge().
@param c The xcb connection.
@param se A value returned from xcb_register_for_special_xge(). NULL is allowed

-- 
A normal person is just someone you don't know well enough yet.
 - Nettie Wiebe