Enums, bitfields and wl_arrays

[Nils Chr. Brause]

Hi,

Pekka Paalanen wrote:
> Adding these attributes to XML must not change the signatures generated
> by wayland-scanner.
>
> Why: these are also used in C++, which does not implicitly covert
> between enums and other stuff, which would break the build.
> http://lists.freedesktop.org/archives/wayland-devel/2014-September/017057.html

There are two different types of enumerations in C++11. The C-style
'enum', which behaves in C++ just like it did in C and the modern
'enum class', which makes each enum a distinct type. The
wayland-scanner generates C code and therefore C-style enums. In C++
they are still nothing else than integers (just like in C). Therefore
they don't change any signatures.

Pekka Paalanen wrote:
> Later that thread also brought up two incompatible definitions of a
> "bitfield":
> - a type where bit-wise logic operations make sense
> - a type where all listed values are powers of two (POT), and bit-wise
>   logic operations make sense
>
> As a practical example, is wl_output::transform a bitfield or an enum?
> - it is used as an int, not uint
> - it lists all possible values
> - the listed values are not all POT
> - bit-wise operations make sense (check for flipped)
>
> Arguably it should have been an uint, but I don't think we can change
> it now.

I have a rather pragmatic view at this: If it looks and feels like a
bitfield, it is a bitfield.
And when looking an the definition, it for all the wold looks like a
bitfield to me.
Bit 0 means 90°, bit 1 means 180° and bit 3 means flipped.
The signedness doesn't matter for a bitfield, since it is just a
collection of bits without a numerical meaning.

Pekka Paalanen wrote:
> There is a paradox: if the new attributes affect codegen for some
> languages in a way that will break the build (which is exactly the
> reason why they are wanted: to enforce type-safety), we cannot add
> these attributes to the existing protocols, most importantly
> wayland.xml, because it would "break existing code".

If the correct types have already been used before, the changes
shouldn't actually break any code. If they do, that means that the
code was invalid in the first place (e.g. enum X used where enum Y is
required orr ORing together non-bitfield values).

Pekka Paalanen wrote:
> Should we make any stability guarantees towards non-C bindings
> generators that exceed what we need for C?

It should at least be guaranteed, the the enum and bitfield attributes
are correct. And that can ultimatly only done by a human. The scanner
might be able to detect if a specified enum actually exists, but only
a human can tell if it is the correct one.

Pekka Paalanen wrote:
> yeah, adding the interface name makes perfect sense. It could be
> optional if wanted. No dot would mean the enum is in the same
> interface, a dot would signify a specific interface. I don't think
> there is any use for an anonymous global namespace like Bill mentioned.

Sounds good to me. Although I think it would be easier to implement,
if we'd just use the dot notation everywhere. This would result in
less code and (statistically) less bugs.

Auke Booij wrote:
> The enum and bitfield attributes are in principle for documentation
> purposes only.

No. The whole point of the enum an bitfield attributes is to help
non-C languages to generate type-safe bindings.

Auke Booij wrote:
> The enum and bitfield attributes may also be used by
> bindings, but only in such a way that code written prior to the
> specification of these attributes still works after their
> specification.

I think every language binding should ultimately decide for
themselves, how they are using the new attributes. There is no way you
can dictate anyone how to use them.

Pekka Paalanen wrote:
> We could have a "strict mode" to wayland-scanner, where you need to
> feed all relevant additional XML files also, and the check would be
> cross-file then, erroring on all unknown links. Then we'd just change
> our builds to use this mode.

This would be very useful to to detect misspellings in interface names.

Bryce Harrington wrote:
> Sounds like might be something worth adding to distcheck.

Absolutely!

Auke Booij wrote:
> I agree with your concern. However, note that "for documentation
> purposes" does not mean that it is just a documentation string: we
> document a very clear and precise fact, for the purpose of
> understanding the API (ie documentation). My previous patches indeed
> do some checking wrt enum name cross-matching. This would have to be
> extended for enum names that refer to a different interface.

You shouldn't write "for documentation purposes only" then, as it is
clearly not. It is mainly for the type-safety of non-C
language-bindings.

Cheers,
Nils