[Xcb] about api changes

[Jamey Sharp]

Guess I'm a little late to the party... Sorry my response is long, but
you folks said a lot. ;-)

On Fri, Jun 08, 2007 at 06:26:38PM +0200, Christoph Pfister wrote:
> This way it should be clear when to use *_next(...) and when not (you
> can assume that whenever you do something else than dereferencing the
> data pointer of a *iterator_t you're on the wrong path).

You're always doing something wrong if you're manipulating the pointer
in an iterator_t. If you want direct pointer manipulation, use the array
form, not an iterator.

On Sat, Jun 09, 2007 at 02:46:02PM +0200, Thomas Hunger wrote:
> If I understand you correctly then you would remove the last function. 
> The last function is needed internally though, so it cannot be 
> removed but could be made private.

It can't be made private, if that means 'static', since other extensions
may need it.

> Second, it makes the API more consistent. Every list with a type that 
> has an iterator can be asked for that iterator. Removing the last 
> function would remove that feature and the user would need to know if 
> the type is memory-adjacent or not.

Yes, and that would make me sad. :-)

On Sat, Jun 09, 2007 at 01:00:21PM -0700, Barton C Massey wrote:
> In message <19a3b7a80706090629m7634c94bx4014113f8692bdb2 at mail.gmail.com> you wrote:
> > There are in fact three ways with the current api:
> > a) get a pointer to the first element + advance yourself
> > b) get an iterater + advance yourself
> > c) get an iterator + use the _next() function
> 
> My original intent was that (c) be possible for *all* list
> types; I didn't realize that at some point we lost the
> iterators for continuous lists, but IMHO we should put them
> back.

We have iterators for all lists, with one exception--lists of primitive
values like CARD32 or char. I don't think there's a problem here.

On Wed, Jun 13, 2007 at 01:16:54PM +0200, Christoph Pfister wrote:
> Am Mittwoch, 13. Juni 2007 00:02 schrieb Thomas Hunger:
> > The iterators could be used by extension protocols. ... A different
> > example is the RECTANGLE iterator. It is not needed in xproto, but
> > xfixes has a reply with a list of RECTANGLEs, so the iterator is
> > needed.
> 
> A possible problem with that (oh - currently I seem to detect them
> all) is when you have one place where you have those elements stored
> in continuous list and one place where you have a non-continuous list.
> Right, the iterator structure itself isn't affected by that, but the
> accessor functions are - so in theory you would need to name the
> accessor functions not xcb_<it-name>_* but xcb_<context>_* - luckily
> non-continuous lists aren't used much and this problem hasn't arised
> (yet) ...

I don't understand. A list of fixed-length elements is a list of
fixed-length elements no matter what context it occurs in. Yes, finding
the start of the list is context-dependent--that's why we have
xcb_setup_roots_iterator, not a generic xcb_screen_iterator function,
for example. But once you've found the start, you can always access it
the same way, no matter how you got it.

On Tue, Jul 10, 2007 at 09:27:23AM -0700, Ian Osgood wrote:
> On Tue, 10 Jul 2007, Thomas Hunger wrote:
> > 1) Remove the xxx_request_t structures from the headers. They are  
> >    only needed internally to pack data for requests. The
> >    opcode-defines could go as well. Are they useful for anything?
> 
> They are useful for protocol dissectors and documentation as well as  
> libxcb internals.

The opcodes weren't in the header until relatively recently. They were
added there so that the header can be used by the X server, which can
also use the request structure definitions. That isn't being taken
advantage of yet, but I'd like to support it.

It's also sometimes useful to have the application construct the request
and call xcb_send_request directly. For example, I have various test
cases that do this in order to reuse the same packed request multiple
times. This might also happen automatically by generating 'extern
inline' copies of request functions, as proposed in bug 6687.

For all these reasons, the definitions should be publicly available.

> How about splitting them into a separate header file? This would be  
> similar to how the current xlib and extension headers are split into  
> <ext>.h and <ext>struct.h.

I really like this proposal! We still need to include the struct header
from the main header to preserve API compatibility, so compile time
won't be improved any. Should we decide to make an API break here later,
though, at least it'll be a one-line change in XCB, and a one-line fix
in callers.

> > 2) New naming conventions in structs/replies. The field-names in
> >    replies and structs (e.g. nameLen-> name_len in xprint.xml). This
> >    could be solved in two ways: a) apply naming filter to all names
> >    or b) write them correctly in the xml files.
> 
> I think the idea was that our XML descriptions would allow us to put  
> in symbols verbatim from written documentation (such as the printed X  
> protocol references) and the parser would be powerful enough to  
> transform those symbols into our chosen naming convention. So  
> studlyCaps would auto-convert to xcb_studly_caps_t or XCB_STUDLY_CAPS  
> etc. depending on what kind of object the symbol was describing.   

That was the idea, yes. And yes, we should have done a) at the time of
the last API change. It's worth noting should we decide to have an API
break later.

On Wed, Jul 11, 2007 at 06:41:36PM +0200, Thomas Hunger wrote:
> If the rename filter is changed so that numbers are not separated we 
> would have x1, x2, ... but some requests would look strange:
> "PolyText8" would become "poly_text8" instead of "poly_text_8" (the 
> former looks strange to me).
> ...
> It seems hard to be consistent _and_ good looking if we handle 
> everything with the same filter...

Not at all hard, if we annotate the XML with what we want. This is
essentially the same problem that Eamon Walsh was trying to solve with
the "extension-multiword" attribute. But what I would do is insert a
space in every name where we want a word-break but the algorithm
wouldn't automatically generate one.

In other words, change the filter to not separate numbers, but call the
request "PolyText 8".

On Wed, Jul 11, 2007 at 01:22:46PM -0400, Jeremy A. Kolb wrote:
> I actually kind of like "poly_text8" but I also like enum_name_1.  I
> think we can be allowed to treat enum names and functions differently.
> They should probably follow the same rules in the XML but they don't
> need to in the generated binding.

Yes, picking rules based on the kind of symbol being generated is also
perfectly reasonable, if it helps.

On Wed, Jul 11, 2007 at 12:38:36PM -0700, Barton C Massey wrote:
> IMHO the problem isn't so much consistency between function
> names and field names. It's just getting the naming filter
> reasonable.

+1

> One might also question whether it's worth breaking the API
> over any of this: I'm in the camp of folks who thought the
> pre-renaming scheme was fine, so I'm obviously the wrong
> person to ask :-).  Opinions?

In general, I don't think it's worth breaking the API to get more
consistent names. On the other hand, I don't feel nearly so bad about
doing new major revisions for extensions. Though I'm not sure how to
properly version changes that change API but preserve ABI, such as
structure field renaming.

Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20071105/6c76d66b/attachment.pgp