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

[Pekka Paalanen]

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