[xcb] Memory management in XCB (was: XCB polling and single-threadedness)

[Andy Howe]

>In order to deal with the inherent ambiguity when a function returns a
>pointer, (to free or not to free?), I've been leaning toward following
>the following stylistic conventions in most of my code:
>
>1) In general, avoid the ambiguity by returning data in storage passed
>   into the function.
>
>2) When returning a pointer is necessary, clearly indicate in the
>   function name whether the function is allocating memory that must
>   be freed, (eg. foo_alloc, FooAlloc, FooCreate, etc.).
>
>3) Provide corresponding "free" functions to balance any functions
>   that allocate memory, (eg. foo_free, FooFree, FooDestroy, etc.).
>
>So, looking at the case in hand, I would vote for following (1) and
>having XCBWaitEvent and XCBPollEvent fill in an XCBGenericEvent passed
>in to the function. Of course, this is similar to what Xlib does.

I'm leaning the same way as you are. I think in the case of events,
doing it this way has advantages. It allows you to return an integer
from the function so you can check for errors easier. This doesn't
really matter in XCBWaitEvent() where it will wait until the event
comes, and return 0 if there is an error. The problem comes with
XCBPollEvent(). XCBPollEvent() returns 0 if there is currently no event
on the queue. If we were able to return an integer from XCBPollEvent(),
we would be able to, for example, return 0 if no events are in the
queue, 1 if there are more events in the queue, and -1 if there was an
error. 

I was also considering an XCBPeekEvent() function, that looked for an
evet of a certain type on the queue, and returned that event, but didn't
remove it from the queue. This function would have similiar return
values to XCBPollEvent(), since it might return a 0 pointer even if
there was no error.

>I glanced through xcb.h and the common case where functions return a
>pointer there is with all the *Rep returns. My style tip (2) doesn't
>help much as the protocol spec. already gives us names with Create,
>Destroy, Alloc, and Free in them. I haven't really programmed in XCB
>enough yet to make any recommendation on whether this part of the API
>should change or not.

I think we should stick to returning pointers to replies. Some of the
replies have a variable size, such as the reply for RenderQueryFormats().

Perhaps a FreeReply() function that is a wrapper free()?


---Andy Howe