Enums, bitfields and wl_arrays

[Bill Spitzak]

On Mon, Oct 5, 2015 at 6:03 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:


> For me, that depends only on what requirements a "bitfield" has. Does
> it have to be uint? Do the values have to be POT? That's all up to you,
> as it has no effect on C bindings nor generated documentation other
> than wording.
>
>
I believe it is ok for the langauge binding to be incapable of producing
negative values for an enum argument, even if it is declared as an int
instead of a uint. I also feel that if, after careful examination, it is
determined that no working program would ever try to send or interpret a
negative value, that the use of int instead of uint be defined as an error
in the xml file, and fixed without changing the protocol version.

Non-power-of-2 names are a requirement, and are trivial to support.

  enum {
    FLIP_VERTICAL = 1,
    FLIP_HORIZONTAL = 2,
    ROTATE_180 = 3 // so programmer does not have to realize the 2 flips
look like a rotation
  };

If a language really can't deal with them, then it can skip those values. I
find it hard to believe there is any such language! It can however make it
impossible to bit-test against a non-power-of-2 value.

For both enums and bitfields it is also useful to give more than one name
to the same value. For instance a "modifier" name used when building a
value, verses a more obvious name for the value that happens to equal that
bit. It can also be used to fix typos or replace unusual syntax with more
standard syntax, without breaking the interface. If a language cannot deal
with this it can use only the first name for a given value.

The condition "one uses bitwise operations" is up to interpretation and
> so is not a clear restriction. Do you want to actually pose any
> restrictions, e.g. on the possible named values?
>

There is a "minimum" set of bitwise operations that must be supported. I
believe these are:

* Ability to "or" any two values of the enum and produce a valid value of
the enum.

* Ability to test any value of the enum against a compile-time constant
enum value that is a power of 2, to see if a particular bit is on.

That does not mean a language binding *can't* implement other operations on
the bitfield. The language binding is free to implement anything it thinks
makes sense (turning bits off, flipping them, testing against non power of
2 including all/any variations, testing against variables, etc).


> Or would you have restrictions on the values if the enum is not defined
> as a bitfield? E.g. would you deny bitwise operations on non-bitfields?
>

No. A language binding is free to implement any operations it wants on the
enums. It can support binary operations on non-bitfields. The main reason
for the bitfield indicator is because supporting bitfields is often
difficult and results in cryptic error messages, and thus language bindings
would like to know when they don't have to bother doing this. The fact that
it can produce some compile-time errors for misuse in some language
bindings is an added bonus.

Similarly it seems like an "open" indicator that can be added to enums
(including bitfields) would help, as it sounds like some languages make it
difficult or cryptic to allow casting of arbitrary numbers to the enum
value. The "open" flag would be an indication that the language binding
needs to support this. The lack of it does *not* mean that a language
binding must prevent casting of arbitrary numbers to the enum.

All this syntax *never* says "you can't do something" to a language
binding. It is more of an indicator that something is allowed. For instance
it sounds like none of this syntax is going to stop the C binding from
allowing any constant or any raw number from being passed to as an enum
value. That is ok because the syntax never says "you can't do that".

Yes. Making dotted optional has the possibility to reduce renaming
> changes when bumping an experimental protocol as per the recent
> suggestions, or when stabilizing it.
>
> Keeping it optional has some pros, and no cons as I can see.
>

That seems right, and it matches the current patches. I think a version
that does not support cross-interface enums can be done first (with the
proposed patches) and then this syntax (supporting dots in the enum names)
added as another patch.

I feel like it is acceptable to limit the enums to being in the same xml
file (plus any includes it does) for now. Does anybody know of any
counter-examples (for instance desktop shells using enums from wl_shell).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151005/0620b4dc/attachment.html>