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

Bill Spitzak 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 mailing list