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

[Auke Booij]

On 20 April 2015 at 09:03, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> Hi,

Thanks for taking the time to respond. I'll address your issues one by
one, but the overarching picture is that such typing information
should and would not be interpreted by bindings as a promise, but
rather as a hint.

> I'm starting to think that using the name "enum" may have been a minor
> mistake. We are using it to define namespaced constants in the XML
> files, similar to how you use #define in C with some naming conventions.
>
> True, we use the enum type defitions to define these constants in C
> rather than #defines. I'm not sure if that has any more rationale
> behind it than it was convenient and allows debuggers to explain the
> values when cast to the enum type.
>
> Nothing guarantees, that an <enum> element strictly describes a complete
> enumeration or even a bitfield. You can have entries which contain
> several bits of a bitfield. You don't have to list all allowed
> entries, and so on. You could even have an <enum> that lists only
> special values and then say a set of other values are allowed, e.g.
> list some negative specials and say all positive values are also
> allowed. We have never excluded this kind of use, though I don't think
> we use it in the core. It doesn't say anything about extensions not in
> core, though.

Perhaps it is worth emphasizing that this is not about making
guarantees (although they would be much appreciated). This is about
being able to make an educated guess what the most appropriate API
would be.

Currently, when my bindings encounter an enum, they basically tell the
user "uhh, it's an integer...", which, in the context of richly typed
languages, is extremely awkward. It would be much better if I could
tell the user "Well, here's this bitfield object, and here are some
flags for you to play with. Oh and by the way, really it's just a
packaged integer." This would expose the full richness of the
underlying C API (without breaking in the way you suggested), but does
a much better job at providing something more sane (in the context of
richly typed languages).

> Enumerations could be incomplete. For instance in the current
> xdg-shell.xml proposal in Weston, xdg_surface.state definition says
> that others are welcome to use other values from their own ranges.

... and as per the above, this would be fully allowed, since the
internal integer representation is still available.

> Also, adding the strict type information to the XML spec has no benefit
> for C, which is the de facto language for Wayland core developers. A C
> compiler also does not raise errors if you violate the rules.

It also does not raise errors if you mismanage your memory
(uninitialized memory, memory leaks, buffer overflow...), or if you
forget to deal with a certain input combination, or if you declare but
not define a function, ...

With all due respect, this is not a good reason to block other
languages from attempting to provide such information. If bindings
erroneously not compile (ie. they error our while they shouldn't),
then that's their problem, not yours. But this will typically hint at
some underlying misunderstanding. In fact, in many occassions it was
due to the Haskell typing system that I investigated internals of
wayland, which taught me about all kinds subtleties I'm glad I didn't
miss. The enum debate fits squarely in this kind of situation.

> Making the enum rules more strict has a possibility to break existing
> users, but to me it is unclear if the benefit would outweigh that
> con or the freedom.

Again, consider this the responsibility of bindings writers.

> On the wire, an enum or bitfield is still just an uint (or int), and a
> buggy client or server may cause the other to receive illegal values.
> Do the strongly typed languages have checks against that? Can you
> define what happens if the value is illegal for an enum? Or do you have
> to write that check manually in any case?

In my case, I would really just expose a nicely packaged integer value
(ie. the wire value), along with an API to e.g. match flags, or match
enums. In other words, this would be perfectly allowed. But the, say,
bitfield API would make much, much more sense from the user's point of
view: bitwise computations are not just uncommon in Haskell, they're
virtually nonexistent. And as long as the user wants to follow the
hint and interpret the value as a bitfield, say, the user can do that.
And if the user knows that something new was introduced in the
protocol, then this information is available as well.


I hope this answers your questions.