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

[Josh Triplett]

On Sun, Jul 20, 2014 at 10:11:42PM +0200, Daniel Martin wrote:
> 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.

That could work for the type names, but anonymous unions for field names
would need to appear in the type definition.

> > 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.

Ah, I see; looks like that would actually change the ABI as well.

> 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.

Likewise, this seems like it would change the ABI.

Not impossible, but it would require a great deal of care, and we'd want
to make sure we got everything changed that needs changing in one pass.

- Josh Triplett