[PATCH wayland] Add "enum" attribute to "arg" elements
spitzak at gmail.com
Thu Apr 23 11:53:59 PDT 2015
I think there may be some confusion about how this would be used by a
language binding, and why bitmap is necessary, and also why it has to be
on the enumeration.
Imagine an interface called Widget, and it has two methods
set_type(Type) and set_flags(Flags). set_type takes an enumeration
called Type and set_flags takes a bitmap called Flags. Type has two
values Left and Right. Flags has two non-zero values A and B.
"widget" is an instance of Widget in this language. Here is how the two
messages might look written in this language:
The following do not compile. In most languages this is because there is
a type mismatch between the argument and the expression used to set it:
widget.set_type(43) // error!
widget.set_type(Widget.Flags.A) // error!
widget.set_flags(Widget.Type.Left) // error!
widget.set_flags(0x1349) // error!
However (and this is why I don't think "documentation only" or
"strictness" is needed) the languages can provide a method to force the
above things to compile. This usually involves adding some extra syntax
such as a cast, the extra code makes it clear to the programmer that
they should be careful:
(yes the language binding could prevent this, but programmers writing
direct Wayland api are already wading into dangerous waters and can
probably be trusted to do this correctly. So for now I don't think there
is any need for a strict control).
The reason for the bitmap is because this should work:
widget.set_flags(Widget.Flags.A | Widget.Flags.B)
but this should not work (either you cannot or the two values together,
or the result of or is the wrong type):
widget.set_type(Widget.Type.Left | Widget.Type.Right) // error!
The binding generation has to know whether it is a bitmap so that it can
make these two cases behave differently.
You may think this is minor detail and it would be ok to or any values
together, and yes that would probably not confuse programmers able to
write Wayland api. However the real reason is that supporting the or is
much more complex in some languages (C++ for example) and thus binding
generators would like to avoid it if possible.
The reason the bitmap indicator has to be on the enumeration and not the
method is because of this:
var x = Widget.Flags.A;
if (foo) x |= Widget.Flags.B; // ***
The language has to know the legality of the statmeent marked with ***.
It cannot depend on knowing the result will later be used for the
set_flags request. Therefore the bitmap attribute has to be on the type,
not the request.
More information about the wayland-devel