[PATCH wayland] Add "enum" attribute to "arg" elements

[Jeroen Bollen]

Hello,

I do think that docenum and enum should be split up. I don't really get the
purpose of docenum though. Even if an enum can be extended, that extension
would technically be an extension to the protocol, would it not?

> Completeness of enums is information that can be encoded in strongly
> typed languages, but I do not think such guarantees are necessary.
> Bindings should be able to deal with new constants not listed in the
> protocol. If we guarantee completeness of enums, I expect we will get
> all kinds of backwards compatibility issues.

I do not quite agree with this. If an application encounters an enum it's
not familiar with, it should output a warning or an error. The bindings
should generate the code to be used by the application. If the application
wants to extend the protocol, they'll have to extend the specification.

As for the bitfields, I do agree it makes more sense to have them in the
argument tags, for the reasons already mentioned.

> That would be solved by documenting the XML language, including
> guidelines for generator writers. I think there are things that
> wayland-scanner cannot communicate, especially when they do not really
> exist in C.

I can only agree with this.

Thanks
 - Jeroen

On Thu, 23 Apr 2015 at 10:38 Pekka Paalanen <ppaalanen at gmail.com> wrote:

> On Thu, 23 Apr 2015 10:17:12 +0200
> Auke Booij <auke at tulcod.com> wrote:
>
> > On 23 April 2015 at 08:38, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> > > On Wed, 22 Apr 2015 11:47:51 +0200
> > > Auke Booij <auke at tulcod.com> wrote:
> > >
> > >> On 22 April 2015 at 08:34, Pekka Paalanen <ppaalanen at gmail.com>
> wrote:
> > >> > I also think this discussion is going off-topic. You wanted to add
> > >> > annotations to the XML, so you could find out about enum and
> bitfield
> > >> > arguments, so let's keep to that. There is value in simplicity.
> > >> >
> > >> >
> > >> > How about this:
> > >> >
> > >> > Add three new, mutually exclusive attributes for <arg> tags:
> > >> >
> > >> >         docenum="enumname"
> > >> >
> > >> > Docenum would be for documentation linking only, and should not
> affect
> > >> > code generation. The effect would be in the documentation to add a
> link
> > >> > to the definition of the "enumname" <enum>. This attribute is
> > >> > applicable for both int and uint type <arg>s.
> > >> >
> > >> >         enumeration="enumname"
> > >> >
> > >> > Enumeration would be a doc link, but also specify that the <enum>
> > >> > "enumname" is a complete enumeration: no other values are legal. You
> > >> > can use this for code generation. You will rely on interface version
> > >> > negotiation to avoid unknown values in case you have an old
> definition
> > >> > of the interface and your opponent is using a new definition which
> > >> > added values. This attribute is applicable for both int and uint
> type
> > >> > <arg>s.
> > >> >
> > >> >         bitfield="enumname"
> > >> >
> > >> > Bitfield would be a doc link, but also specify that the values
> listed
> > >> > in <enum> "enumanme" can be orred together to form new legal values.
> > >> > Bits that are not settable by using the listed values must be zero.
> You
> > >> > rely on the interface versioning to avoid getting undefined bits
> set,
> > >> > just like enumeration relies for adding new values. This attribute
> is
> > >> > applicable only to uint type <arg>s.
> > >> >
> > >> >
> > >> > So, both enumeration and bitfield could be used for codegen, docenum
> > >> > would not. Docenum or nothing would be used for cases that do not
> fit
> > >> > as enumeration or bitfield, including cases where unknown values are
> > >> > always allowed but the interface specification defines what to do
> when
> > >> > encountering one (ignore, use as a literal value, ...).
> > >> >
> > >> > Wayland-scanner would generate the doclink references in header
> > >> > comments, and check that the referenced enum exists and the <arg>
> type.
> > >>
> > >> Two comments on this.
> > >>
> > >> 1. I do not think it is necessary to distinguish between docenum and
> > >> enumeration. At least for me, I am not asking for any new guarantees
> > >> with regards to completeness: sure, new constants may be added on the
> > >> fly. All I want is semantic information: which (u)int refers to which
> > >> enum? And this data would be provided by your docenum (which I would
> > >> just call "enum").
> > >
> > > Jeroen seemed to be wanting that. That's why it gets complicated.
> >
> > I agree. Well, if there is support for Jeroen's ideas, I will add that
> > to the scanner.c patch. I am not against them, but I would expect the
> > guarantees to be broken by C code all the time, so there needs to be a
> > solution for that.
>
> I'd rather not, or at least separate these two. We can add the doc
> attribute, and discuss the strictness later. Adding strictness
> constraints later should be as simple as adding more attributes.
>
> However, if strictness attributes affect codegen, it might be difficult
> to add them to existing enums, because it would change the API a code
> generator produces. That is a pretty strong reason to not change
> anything that affects codegen: you may be using an XML file that does
> not have these attributes, or you may be using a generator that does
> not handle these attributes.
>
> Third party XML files are a thing, you don't have control over
> everything. Version requirements on depended-on projects could be used
> to mitigate it, plus perhaps a switch to the generator to ignore the
> new attributes until your code ports to the strictly typed API.
>
> > >> I agree that it should express that OR'ing together any number of
> > >> values from the list should *at least* not be considered a protocol
> > >> error. They may still be disregarded for other reasons, but passing
> > >> OR'ed values in a bitfield should not break protocol, and this is the
> > >> guarantee a bitfield flag should express (IMO).
> > >
> > > I'm not sure about that. The allowance to "or" things together was more
> > > related to the "strict enumeration" enforcement.
> > >
> > > Interfaces should be able to still say, that a certain combination is
> > > illegal and will lead to a protocol error.
> > >
> > > None of it will ever break protocol on the wire level, as it is all
> > > just uints.
> > >
> > > Given this and that they must not affect codegen, what are the
> remaining
> > > differences between enums and bitfields? Enum can be an int, but a
> > > bitfield cannot? Is it worth to have the distinction in the language at
> > > all?
> > >
> > > In the end, is the only really useful thing left the doc linking?
> >
> > Well, for one, there is a semantic difference, which in richly typed
> > languages is not to be underestimated. Perhaps the requirement should
> > be that:
> > at least one (non-empty) combination of listed values OR'ed together
> > results in a new valid value (ie one not listed)
>
> If you talk about richly typed languages, you imply that this will
> affect codegen. The doc linking alone should not affect codegen.
>
> > This is a sort of sanity condition on being a bitfield: it does not
> > require all combinations are valid, but it also distinguishes it from
> > a regular enum.
>
> Is that an important distinction to make? That a bitfield with "too
> many" restrictions must not be a bitfield?
>
> > > It seems the main difference between your and Jeroen's requirements is
> > > that Jeroen wants strict guarantees so that codegen can generate the
> > > strictest APIs in his language.
> >
> > I agree. Like I said, such guarantees are welcome, as long as the
> > situation is also clear for C, so that we don't get any annoying
> > incompatibilities due to misunderstandings between languages. At this
> > point I am not asking for them.
>
> That would be solved by documenting the XML language, including
> guidelines for generator writers. I think there are things that
> wayland-scanner cannot communicate, especially when they do not really
> exist in C.
>
> > I fixed Bill's note on my sample patch, and will publish my
> > intermediary work on my github [0] (probably this will be limited to
> > just two commits, but you can subscribe if you want to).
> >
> > [0] https://github.com/tulcod/wayland/tree/enum-attribute
>
>
> Thanks,
> pq
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20150423/61e06d63/attachment-0001.html>