[Xcb] naming convention again ;)

Jeremy A. Kolb jkolb at brandeis.edu
Mon Dec 12 13:31:06 PST 2005

On Mon, 12 Dec 2005, Jamey Sharp wrote:

> On Tue, Jun 21, 2005 at 10:26:26PM -0400, Jeremy A. Kolb wrote:
> > I just updated my mesa branch and found a mistake that I had made in the 
> > code generation.  While fixing this I noticed (had forgotten) that all of 
> > the lists returned are named "Data".  Clearly this goes against the naming 
> > conventions that we are following, however it is important to have a 
> > consistent name for Mesa's code generation.  I had forgotten about this 
> > but I think it's something that needs to be brought up.
> Hmmm, looks like I failed to reply to this. That may have been because I
> didn't understand it.
> I don't have any problem with using the name "data" for the <list> field
> in any reply that has only one <list> and no other interesting fields.
> Usually the meaning of that list is described by the name of the
> request, and any name you give the list itself would seem redundant:
> XCBGlxReadPixelsPixels would be dumb, for instance. However, in many
> cases it makes sense to give a descriptive name because there isn't that
> overlap: XCBQueryTreeChildren is much better than XCBQueryTreeData.
> If the name "data" were selected just because it makes Mesa code
> generation easy, I wouldn't approve. In that case you should load
> glx.xml from xcb-proto and look up the correct list name for each
> request: this is easy to do when you're already processing a bunch of
> XML anyway, and it's one of the big reasons why we built a protocol
> description language.
> --Jamey

Ah yes.  The problem is that all of these replies have (roughly) 
the exact same format.  The fields had to be called data because there was no 
other way to autogenerate them from the glapi.xml file.  In X11 glx they 
use one structure to deal with all of these GLXSingleReply), and 
something similar when sending the request, we couldn't do the same in XCB.

** This reply structure is used for all single replies.  Single replies
** ship either 1 piece of data or N pieces of data.  In these cases
** size indicates how much data is to be returned.
typedef struct {
    BYTE        type;                   /* X_Reply */
    CARD8       unused;                 /* not used */
    CARD16      sequenceNumber B16;
    CARD32      length B32;
    CARD32      retval B32;
    CARD32      size B32;
    CARD32      pad3 B32;               /* NOTE: may hold a single value 
    CARD32      pad4 B32;               /* NOTE: may hold half a double */
    CARD32      pad5 B32;
    CARD32      pad6 B32;
} xGLXSingleReply;
#define sz_xGLXSingleReply 32

For example in GetBooleanv depending on retval you'll have different lists 
starting at different points in the padding.  If there is only one value 
to return it will be returned in pad4.  Since this is repeated for a ton 
of replies it was much easier to give consistent names.

Putting checks in to see which functions are being read to figure out the 
name would be awful since you would have to check for every single name.  
Anyways, I think Data works since in most cases the name would be 
redundant.  But I'll have to check again.


More information about the Xcb mailing list