Enums, bitfields and wl_arrays

[Nils Chr. Brause]

Hi,

Auke Booij wrote:
> I think that we have an agreement in principle, just not in terms (and
> this also goes back to my comment to Victor Berger). What I meant to
> express is that any bindings that violate this rule are on the risk of
> the bindings writers, rather than the wayland and wayland protocol
> developers.
>
> Would you agree with the following? Otherwise please suggest a
> phrasing you would agree with.
>
> [start]
> The purpose of the enum and bitfield attributes is to document what
> arguments refer to which enums, and to document which numeric enum
> values are primarily accessed using bitwise operations.
> Additionally, the enum and bitfield attributes may be used by other
> code, such as bindings to other languages, for example to enhance type
> safety of code. However, such usage is only supported if the following
> property is satisfied: code written prior to the specification of
> these attributes still works after their specification. In other
> words, specifying an attribute for an argument, that previously did
> not have an enum or bitfield attribute, should not break API. Code
> that does not satisfy this rule is not guaranteed to obey backwards
> compatibility.
> [end]

Personally, I'm fine with that. :)

Pekka Paalanen 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.
>
> If you agree on the restrictions and requirements, then we can see what
> it applies to.
>
> 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?
>
> 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?

A bitfield doesn't have to be an unsigned integer and it doesn't have to be a
POT either. It can be anything that holds a series of bits, as a bitfield
doesn't have a numerical meaning.
In my opinion it's also not relevant whether an enumeration is signed or
unsigned or a POT or NPOT. Just think of it as a mapping from a particual
bit-pattern (which it is on the wire) to a meaning.

(Maybe this view comes from the years of working with VHDL, where everything
is just a bit pattern and it's up to the user to put meaning into it. C is very
close to that, though, as you can cast whatever you want)

Pekka Paalanen wrote:
> What is a bitfield and how does it differ from non-bitfield enum?

In a bitfield, every single bit (except the unused ones) has a distinct
meaning (see my format example). In an enum, that is not the case.

Bill Spitzak wrote:
> 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.

See above, the signedness of an enumeration doesn't really matter. ;)

Bill Spitzak wrote:
> 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.

Since a language binding should support unknown values anyway, I don't quite
see the benefit of an 'open' flag.

Bill Spitzak wrote:
> 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).

Do you mean, you don't want to mark enums if they are defined in another XML
file? I would prefer having marked every enum properly from the beginning.