[Xcb] Experiences with XCB

[Ian Osgood]

On Sep 19, 2006, at 11:41 PM, Jamey Sharp wrote:
>
> On Wed, 20 Sep 2006, Ori Bernstein wrote:
>> My experience with XCB was mixed. My first thought was "Where are the
>> docs?!?".
>
> Heh. I sympathize, kind of. But were you looking for documentation on
> protocol stubs, or on the core API? We've had pretty OK  
> documentation on
> the core API for more than a year, and of course the protocol stubs  
> are
> rather exhaustingly documented by the relevant protocol  
> specifications.

If you're willing to search for them in CVS and read the Postscript  
or troff (?) source files.

Xorg desperately needs volunteers to help modernize their documentation.

> While we intend to integrate all of that documentation together
> eventually (actually, we're really just waiting for a volunteer to  
> just
> do it), are you saying that wouldn't have helped you? Everything we  
> plan
> to provide was available to you already, after all... :-)
>
>> The "strong typing by structs" was another annoyance, although I  
>> guess
>> my use case is nontypical, since I had to interact with the X  
>> server's
>> DIX, which uses scalars. Lots of conversions were going on.
>
> Yeah, that is a bit unusual. :-)

I'm with Ori. This is an interesting C idiom, but it quickly becomes  
inconvenient. I haven't seen this technique used in any other C  
projects.

It also makes using constants more painful. For example, you can't  
simply  use XCB_CURRENT_TIME when you need it; you have to declare an  
xcb_timestamp_t structure with XCB_CURRENT_TIME in it and use that.

It is also funny to strengthen typing with these structs for some  
things, but lose typing altogether for other things, like the value  
lists used by create_window.
>
>> I still believe the biggest deficiency in the XCB API is that  
>> there is
>> no way to peek the next event in the queue. An example use case: I
>> want to collect all expose events in one function. In my mind, the
>> natural way to do this is peeking the next event (or at least it's
>> type) to decide if I'm done gathering exposures. XCB has no way of
>> doing this, as far as I can see, and it makes some code awkward.
>
> On Wed, Sep 20, 2006 at 08:10:35AM +0200, Vincent Torri wrote:
>> I also have dealt with that in ecore. But I modified a bit my code
>> and, finally, that peek function was not necessary for me. In case it
>> might help you, I get the next event and store it in a global
>> variable, and I use that variable later to check of there's an event
>> or not in the queue.
>
> Yeah, if the application *has* to peek in the event queue, then  
> this is
> the way I would do it. Although for ecore, Vincent, beware of assuming
> that there is only one connection open to an X server. I hope ecore
> doesn't currently assume that... :-)
>
> It still seems to me that the best way to accomplish things like  
> expose
> events, though, is to process events centrally into application- 
> specific
> data structures, drain the event queue entirely, and then do any
> expensive drawing or computation that the events trigger. Then you
> *know* there aren't more expose events, and can already have collapsed
> the ones you got into a single region if desired.

This seems like a frequently asked question. Let's write up sample  
code for several common event-peeking replacement strategies and add  
them to the tutorial and to the FAQ page on the wiki. I think Jamey  
already wrote some code to the mailing list a while back.

Also, isn't there already an xcb_utils/event library? We might be  
able to add some generic code there as well.
>
>> Usually, when I don't find enough doc on how to translate an Xlib
>> function in the tutorial, I look at the Xlib code. It's usually easy,
>> then to get the XCB code.
>
> Hmm. Your approach is sound, but somewhat frightening. ;-)

I did this as well when porting Xlib code. Living code is the  
ultimate documentation.
>
>> In gneral, you are right, there is a lack of doc about xcb. Once the
>> naming convention will be out, I think that I'll make a patch so that
>> doc is generated by doxygen if it is found.
>
> We should be able to run doxygen at freedesktop.org on a regular  
> basis,
> and keep the generated pages at http://xcb.freedesktop.org. We're  
> ready
> for that now, I think: I'm again hoping a volunteer will step up to  
> take
> care of it. :-)

[insert sound of chirping crickets here]
>
> --Jamey