[PATCH wayland] Add "enum" attribute to "arg" elements
auke at tulcod.com
Thu Apr 23 01:17:12 PDT 2015
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
> 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
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  (probably this will be limited to
just two commits, but you can subscribe if you want to).
More information about the wayland-devel