[Xcb] RFC: The need to break the API. (Im)Possible?

[Daniel Martin]

On Sat, Jul 19, 2014 at 01:37:58PM -0700, Josh Triplett wrote:
> On Sat, Jul 19, 2014 at 10:11:41PM +0200, Daniel Martin wrote:
> > Dear list readers,
> > 
> > we've had a few places in proto we couldn't fix correctly as a correct
> > fix would break the API of libxcb, recently. Then I see a lot of places
> > in proto that should be changed to represent the actual protocol more
> > precisely. To mention a few:
> > - replace valueparams with switch/bitcases
> > - replace unions with switch/cases (yes, they aren't supported yet)
> > - or just the typo "permament":
> >     http://cgit.freedesktop.org/xcb/proto/tree/src/xkb.xml#n471
> > 
> > I would like to contribute such changes to proto, but they all break the
> > API of libxcb. So, does anyone has an idea how we can handle such
> > changes?
> 
> First of all, I'm somewhat less concerned about breaking *API* than
> about beaking *ABI*.  A change like s/permament/permanent/ would break
> API compatibility, but would not break the library ABI, and would not
> require an SONAME change.
> 
> In some cases, we could generate new API without breaking the old.  For
> instance, in the case of "permament", on any platform that supports
> anonymous unions, we could support both field names; for types, a
> #define would preserve API compatibility.  (Perhaps add a "compat-names"
> attribute?  Also, please generate a comment next to the compatibility
> names saying "Backward compatibility", so people know the preferred name
> when reading the definition.)

The workaround with a #define sounds okay. But, I would not like to
generate it from an additional attribute. I would add it to a
handwritten header to libxcb.

> In the valueparam and union cases, what would the new API look like
> compared to the old, and could we in any way preserve the old API as
> well?

There's an example in sync.xml how the replacement of a valueparam would
look like (here it actually fixed a bug):
    http://cgit.freedesktop.org/xcb/proto/commit/src/sync.xml?id=e6a246e
With that you end up having a struct to access the members (values),
whereas with the valueparam you had a list to iterate the values. So,
I don't see any possibility on how to preserve the API in such a case.

For some unions it might be possible to keep the API, i.e. the ones in
xkb having a distinct 'type' member. But, for unions without, i.e.:
    http://cgit.freedesktop.org/xcb/proto/tree/src/xproto.xml#n1023
this may not work.

> > PS: Replacing unions with switch/cases is one requirement if anyone ever
> >     wants to generate the byte-swapping code for the server. ;)
> 
> Which I'd love to see.
> 
> - Josh Triplett