Hi, Auke Booij wrote: > 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. > > 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]
Personally, I'm fine with that. :) Pekka Paalanen wrote: > 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? A bitfield doesn't have to be an unsigned integer and it doesn't have to be a POT either. It can be anything that holds a series of bits, as a bitfield doesn't have a numerical meaning. In my opinion it's also not relevant whether an enumeration is signed or unsigned or a POT or NPOT. Just think of it as a mapping from a particual bit-pattern (which it is on the wire) to a meaning. (Maybe this view comes from the years of working with VHDL, where everything is just a bit pattern and it's up to the user to put meaning into it. C is very close to that, though, as you can cast whatever you want) Pekka Paalanen wrote: > What is a bitfield and how does it differ from non-bitfield enum? In a bitfield, every single bit (except the unused ones) has a distinct meaning (see my format example). In an enum, that is not the case. Bill Spitzak wrote: > I also feel that if, after careful examination, it is determined that no > working program would ever try to send or interpret a negative value, that > the use of int instead of uint be defined as an error in the xml file, and > fixed without changing the protocol version. See above, the signedness of an enumeration doesn't really matter. ;) Bill Spitzak wrote: > Similarly it seems like an "open" indicator that can be added to enums > (including bitfields) would help, as it sounds like some languages make it > difficult or cryptic to allow casting of arbitrary numbers to the enum value. > The "open" flag > would be an indication that the language binding needs to > support this. The lack of it does *not* mean that a language binding must > prevent casting of arbitrary numbers to the enum. Since a language binding should support unknown values anyway, I don't quite see the benefit of an 'open' flag. Bill Spitzak wrote: > I feel like it is acceptable to limit the enums to being in the same xml file > (plus any includes it does) for now. Does anybody know of any > counter-examples (for instance desktop shells using enums from wl_shell). Do you mean, you don't want to mark enums if they are defined in another XML file? I would prefer having marked every enum properly from the beginning. _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
