Protocol (scanner) proposals

[Auke Booij]

I am in the process of writing bindings to Wayland for Haskell, and
have run into some issues which I think you may be interested in
solving.

They all relate to the protocol files.

1. Haskell is a very richly typed language, which means that if two
integers have different meaning (e.g. length of an array and a file
descriptor), then they should have different types. In the wayland
protocol, you have assigned some semantic meaning to a particular
class of integer values you guys call "enum" (*) (e.g. wl_shm.format).
This is great to have for both programmers and binding writers, except
that to properly process this in the bindings, I need to know which
enum is used where: which message arguments have the "type" of which
enum.

Therefore I propose to add a new "enum" attribute to the "arg" element
in the XML specifications, whose string value simply corresponds to
the name of the enum whose values it assumes - but this should only be
used when the "type" of the "arg" is an "int" or a "uint" (?).

1a. (*) "enum" is short for "enumeration": a complete list of possible
values it can have. But some of your "enum"s can actually assume
several values simultaneously (or none at all), such as
wl_seat.capability - such "enum"s have a fundamentally different
meaning and technical usage, and I wouldn't call them "enum".

Hence, I propose to add a "bitfield" attribute to the "enum" element
in the XML specifications. If its value is set to "true", then any
number of the values are to be added additively (each at most once) to
be presented as the actual integer value (uniqueness of additions is
to be guaranteed by the protocol designers - in other words, use
powers of 2 for your values).

Note that in this understanding, wl_shell_surface.resize is /not/ a
bitfield, since indeed it /does/ list all possible combinations
explicitly.

This is not a very important proposal to me, but I think
a. it could help people understand the protocol (even though it should
be obvious from the fact that such enums consist of values which are
powers of 2), and
b. it would enable a very minor improvement in the bindings I'm
writing (again, a "bitfield" is a particular kind of type, which the
language has special libraries for - and "actual" enums correspond
very nicely to sum types without parameters, which in the Haskell
world is a big thing).


The general message behind the above is that the more precisely the
protocol is specified, the better I can write bindings. Indeed, to
bind the functions in, say, wayland-client.h, I often dive deep into
the code to see what it really does - a typical state of affairs for
library binders.


2. The current wayland-scanner produces a huge amount of "static
inline" functions. In C, this doesn't make a big impact, but the fact
that these functions are all static means that one cannot link to
them, so that anyone writing language bindings is forced to write C
code calling all the individual functions - whereas linkable functions
often don't even require a single line of C code.

Now, I assume that the "inline" is to help with efficiency, and that
the functions are "static" because you guys somewhat arbitrarily put
these definitions in the header files.

I propose to move the implementations of all these functions to the
various -protocol.c files, ie, to the library, and only put their
declarations in the header files.

This will force an extra call jump. However, this can be fixed by
placing wl_proxy_marshal and wl_proxy_marshal_constructor in the
headers, and making that static inline instead. You have now reduced
the number of "static inline" functions by like, a factor 1000 or
something, but with the same number of jumps, and a much more concise
header file.

Additionally, this would make it possible to place more of the
"internal stuff" actually internally: no more need to even declare
wl_proxy_marshal(_constructor), or the list of wl_interface structs.
Although presumably you guys like having access to internals.

(Don't forget to also move around the add_listener and
get/set_user_data functions.)

Now, I don't know the impact of this change on the ABI, and on
applications linked to the current setup. Presumably stuff linked
against the current wayland won't work anymore, because they link to
wl_proxy_marshal which has now been made "static inline". But
recompilation should fix it, since the functions still exist with the
same names. I think.



I would be happy to work on patches for all presented ideas, but
thought I'd ask for your feedback first.


Bonus input:

3. I am working on a document listing the things I found nontrivial or
unexpected
https://github.com/tulcod/haskell-wayland/blob/master/NOTES.md
You may wish to look at it, to possibly incorporate in your documentation?

4. I think that you should place the protocol files that are currently
in the weston repository (weston/protocol/*.xml) to the wayland
repository, since it may be of interest to other implementations of
compositors as well (and then having to depend on weston would be a
bit awkward).