On 23 April 2015 at 08:38, Pekka Paalanen <ppaala...@gmail.com> wrote: > On Wed, 22 Apr 2015 11:47:51 +0200 > Auke Booij <a...@tulcod.com> wrote: > >> On 22 April 2015 at 08:34, Pekka Paalanen <ppaala...@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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
