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

[Pekka Paalanen]

On Mon, 27 Apr 2015 13:26:39 +0200
Auke Booij <auke at tulcod.com> wrote:

> Apologies for my lack of responses, I have been abroad for a few days.
> 
> On 23 April 2015 at 10:38, Pekka Paalanen <ppaalanen at gmail.com> wrote:
> >> This is a sort of sanity condition on being a bitfield: it does not
> >> require all combinations are valid, but it also distinguishes it from
> >> a regular enum.
> >
> > Is that an important distinction to make? That a bitfield with "too
> > many" restrictions must not be a bitfield?
> 
> Yes, because what the bitfield flag indicates is that it is useful to
> think of the values as flags. It means that the values can somehow be
> combined. If there is no way to validly combine them, then it is not
> useful to think of them like flags. And if the right way to combine
> them is not OR'ing, then what you are talking about is not a bitfield.
> I am not saying it is a kind of value that is unwelcome in the wayland
> API, merely that it is not in the same category as what is usually
> considered a bitfield.
> 
> And indeed some things (e.g. wl_shell_surface.resize and
> xdg_surface.resize_edge) kinda look like a bitfield, but it is up for
> discussion whether they actually are, since it also looks like all of
> the options are explicitly listed, so in that sense we do not need to
> combine values by OR'ing, and it is hence not a bitfield.
> 
> Bill's 23rd of April (pseudo)code is very accurate, and highlights the
> issues I am trying to address in my bindings. Bill, thanks for that.
> 
> Pekka, you keep suggesting "docenum" only be used for documentation.
> However, types in richly typed languages *are* documentation (*). They
> indicate how you should use certain values. The fact that values are
> packaged as a certain enum type *documents* that you should probably
> use them in this or that way, without completely blocking use of the
> raw data (unless Jeroen's plan goes through).

Ok, let me clarify: changing documentation alone cannot cause
failures. That is what I mean by documentation-only here.

Sure, you can use language constructs in a documentative way, but the
main point here is can this cause build or runtime failures if it
suddenly changes.

> (*) In fact, in the case of Haskell, more often than not, you can find
> functions in an API purely by searching for its type: the type
> information of functions documents enough to know their behaviour. In
> some languages, the difference between code and documentation is not
> so clear-cut.
> 
> The entire reason I am asking for this "enum" attribute is so that the
> code I generate is more self-documenting. It does not enable the
> bindings to compute things it otherwise wouldn't be able to: packaged
> (u)ints are still (u)ints. It's to help the user understand the API,
> and unless they know better, suggest how they should interact with
> wayland.

Then I didn't understand your intent before. I thought you wanted to use
the enum types in the API you generate, which in strictly typed
languages means you get build failures if you try to use a value not in
the enum.

If it cannot cause build or runtime failures, then it's fine.

> Jeroen's request, I think, stands separately from this: Jeroen is
> asking for strict guarantees on what values are and are not allowed in
> enums. Perhaps this should be moved into a separate thread?

I (mistakenly?) took that using the types in the API means that you get
these strict value guarantees Jeroen is asking for.

Can you explain how you will use the enum types in the API without
hitting the type checks of a strictly typed language? The answer is
probably language-specific, but that is ok. We only need to answer the
"can it break?" question, and define the attribute semantics so that it
cannot break.

In fact, that is the definition for the "docenum" attribute: changing,
adding, or removing it from the XML file cannot cause any new build or
runtime failures. Otherwise use it any way in a generator you want. It
is similar to the "summary" attribute and <description> tag.

> So in summary:
> 
> - Currently, there is no systematic way to match (u)ints that are
> passed around with enums that are defined by the protocol. This makes
> the <enum>s, from a technical point of view, somewhat disconnected
> from the (u)int arguments.
> 
> - Currently, there is no systematic way to tell if bitwise
> computations on enum values are supposed to be possible (as per Bill's
> example code).
> 
> - Currently, there is no guarantee that only certain (u)int values
> will be exchanged under a given version of a protocol.
> 
> - It would be much welcomed by bindings and documentation generators
> if there would be a *semantic* correspondence between (u)ints and
> <enum>s. This correspondence would merely indicate how certain (u)ints
> are to be interpreted by matching them with an <enum>. This feature
> alone should not generate an API that is in any sense stronger or
> weaker than without such information (iow, access to the underlying
> (u)ints should still be available), but it may look different (e.g.
> (u)ints packaged in a type that refers to the right <enum>).

This is the part I don't get. Either you use the strict types or you
don't? What is the "maybe" option? Generating parallel APIs, and then
the user must know which one is actually the right one to use? I see in
Bill's example there are "forced casts" from arbitrary values to the
type, but this requires the programmer to write those casts.

Note, that "can it break?" also applies to cases where someone is using
an old XML file without these enum attributes (won't know that he
should be using forced casts, because the implementations of the casts
aren't even available) and then switches to a new one with the
attributes. If you can guarantee such a case cannot break, then it is
all fine.

> - In strongly typed languages, hints on generating the right API shape
> for bitfield-style arguments would be welcomed (as per Bill's example
> code). However, details of when something is a "bitfield" need to be
> discussed.
> 
> - In strongly typed languages, guarantees on which enum values are
> allowed in the protocol would be welcomed. However, worries about
> compatibility (both between languages and between versions) need to be
> worked out in detail. Also, how do such guarantees combine with the
> "bitfield" flag?
> 
> - Whereas interface names are global, enums are named locally in
> interfaces. However, there might be a need to refer to another
> interface's <enum>. However, this is a problem that can be solved
> later as it comes up (for now the enum attribute would use local
> names). As far as I am aware, there is no such situation in any common
> protocol right now.

In the end, all I care is about the definition of the new attributes
related to enum. If you really want to write a generator that can break
the build of other people, you can.

I would just want the definition of the attribute be such, that
following it literally, nothing can break even if the attribute gets
added much later than the interface it is used in. Either this, or
adding/removing the attribute is allowed to break the generated API,
which means we cannot add it retroactively to stable interfaces. That
is the difference between documentation-only and not.

We have added an attribute before: allow-null for object type <arg>,
defaulting to "false". It cannot cause failures in cases that weren't
already failing somehow anyway.


Thanks,
pq