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

[Auke Booij]

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

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.

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


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