Enums, bitfields and wl_arrays

[Pekka Paalanen]

Re-adding the CCs: Jeroen, Jason, Boyan.

Jeroen is the one who started the April 2015 thread on this.

On Sun, 4 Oct 2015 22:15:12 +0100
Auke Booij <auke at tulcod.com> wrote:

> This email contains a clear suggestions that I'd like everyone to
> read, not just Nils and Erik. But Nils and Erik brought up a few
> points that I'd like to have settled, since they have been brought up
> quite frequently now.

As Erik wrote on On Sat, 3 Oct 2015 21:05:24 +0200: "... a wayland
'open' enum is not really an enum but a set of pre-defined constants."

This is true and we are trying to retrofit additional semantics to the
definition.

> On 3 October 2015 at 11:14, Nils Chr. Brause <nilschrbrause at gmail.com> wrote:
> > 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.
> 
> So perhaps we should say:
> 
> "An enum can be specified to be a bitfield if the primary interface to
> its numeric value deals with bitwise operations."
> 
> Is that agreeable?

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?

I'd also be wary of using definitions where one is not a superset of
the other. In that case there would not be a "safe default" to pick for
a protocol XML writer, and it might be impossible to fix it after the
interface has become stable.

For example, I would assume that definitions like "only bitfield values
can use bitwise ops, and only non-bitfield values can be NPOT" will
lead to artificial problems.

What is a bitfield and how does it differ from non-bitfield enum?

> > 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.
> 
> It is the "dotless" version that is already supported by my patches.
> The dotted one requires new code. So apart from a single if statement,
> this is not really more work. But I guess this is getting into
> bikeshedding terrain.

Yes. Making dotted optional has the possiblity 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.

> > 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.
> 
> 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.

Yes, this nit-picking on terms is what has made me give up before. This
is a huge time sink.

> 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]

At least I'm fine with that if it gets us forward.

It's more elaborate and less loose definition than what I had in mind:
Do what you wish, but if you use these as API, you're on your own.

Your text is written from the language binding writer's perspective,
hence it gives directions to bindings' writers.

Another approach would be to write it from the XML spec writers'
perspective: what you must, should, and cannot do. Of course it is best
to include both sides, so that the other party does not have to guess.

The difference is that the spec writers' contributions will be
strictly reviewed against this wording, while bindings' writers only
use it as information rather than the law. Like Nils says, we cannot
dictate what language binding developers do, but we *will* control what
kind of XML files we accept (both in patch review and in
wayland-scanner), and we need clear rules for that.

IOW, I'd like the spec to written mainly from the XML spec writer's
perspective because that is authoritative. All wording about language
bindings will be only informative.


> I'd like to suggest that anyone who wishes to further the open/closed
> enums debate suggests a firm specification that we can work with.
> Otherwise we can keep bringing this up, and then someone brings up a
> counterargument, ad infinitum.

Yeah.

I'm going to ask for a new patch set when I reply to the current patch
set. We should be able to continue on the new patches, otherwise I feel
we're just http://www.idano.net/images/stuck-in-the-mud.jpg .


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151005/995d05d7/attachment.sig>