Re: [PATCH wayland] Add enum attribute to arg elements
Am 19.05.2015 09:19, schrieb Christian Stroetmann: On the 19th of May 2015 08:33, Pekka Paalanen wrote: On Mon, 18 May 2015 19:23:20 -0700 Bryce Harringtonbr...@osg.samsung.com wrote: On Sat, May 02, 2015 at 11:52:22PM +0200, Auke Booij wrote: On 19 April 2015 at 14:51, Jeroen Bollenjbin...@gmail.com wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. Since we're only a couple weeks out from a release, and since this obviously is a non-trivial change to the API, I'd be most comfortable if we held this until 1.9 opens, and land it then; that would give us maximum time to test this. Hi, yeah, this is definitely not post-alpha material, because it is changing the Wayland protocol XML language, which is even more fundamental than the wayland.xml itself. Also, with wayland.xml we know what things change ABI, but changing the XML language is much harder to reason about, as the discussion shows. Sorry, but I do not have time to look into this soon. Thanks, pq Aloha I am not sure if enumeration.xsd https://developer.bluetooth.org/ schema/ Documentation/ enumeration_xsd.html and bitfield xsd https://developer.bluetooth.org/schema/Documentation/bitfield_xsd.html might help, but the XML Schema Definitions (XSDs) have the right names, seem to be related, and are included in the General Agreement on Tariffs and Trade (GATT) Schemas found under https://developer.bluetooth.org/gatt/Pages/FormatTypes.aspx on the Bluetooth developer portal. Please, let me correct the email. enumeration.xsd https://developer.bluetooth.org/schema/Documentation/enumeration_xsd.html bitfield.xsd https://developer.bluetooth.org/schema/Documentation/bitfield_xsd.html (GATT) Schemas index https://developer.bluetooth.org/schema/Documentation/indexPage.html Somehow, it seems to be that the access to the Documentation directory on the website bluetooth.org is connected with a user account. C.S. Thanks Best Regards Have fun C.S: ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Sat, May 02, 2015 at 11:52:22PM +0200, Auke Booij wrote: On 19 April 2015 at 14:51, Jeroen Bollen jbin...@gmail.com wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. I am currently in the progress of writing a Wayland binding generator for the Rust language. This language, like many others is strongly typed. To make full usage of this type system, it would be beneficial to know from the specification whether an argument is a bitfield, and what enum type it takes. Surely there are more people who generate bindings to these strongly typed languages. How have you fixed the issue? Are there patched versions available, and maybe pending to be merged? I have looked around a bit, and didn't find anything, but then again, I'm not familiar with Wayland development. (This is the first time I use a mailing list!) Much appreciated, Jeroen Bollen ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel Based on the discussion I wrote two patches: one for the wayland.xml (and wayland.dtd since the fact of the matter is that that file is still there), and one for scanner.c See 5dc0112f734d23d65a2bf9a78f11463d0294b6c7 and b6d5659c650056f66267f3f20fdbaf724138a61b in [0]. Is this a good format for sending patches? Or are actual patch emails preferred? Actual patch emails are preferred, since our tooling (patchwork and phabricator) only know to identify patches here on the list. The scanner.c code checks that the enum attribute of an arg is the name of an enum in the same interface. In that case, it checks that the type of the arg is an int or a uint, and if the enum had bitfield set to true, that the type was indeed uint. If these properties are not satisfied, the scanner dies. Is that what was expected? Thanks for following up. I went through the earlier discussion, and my take is that there were some strong opinions but it sounds like it resulted in a consensus. It looks to me like your patch implements this consensus, but to be 100% certain it would be good to see thumbs-up by pekka, jeroen, and others that participated in that thread. It also needs to be documented, at least in wayland/doc/publican/sources/Protocol.xml, and possibly other places where types are discussed. Since we're only a couple weeks out from a release, and since this obviously is a non-trivial change to the API, I'd be most comfortable if we held this until 1.9 opens, and land it then; that would give us maximum time to test this. (Speaking of testing, it would be Really Nice to have a test for the scanner.) Bryce ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On 19 April 2015 at 14:51, Jeroen Bollen jbin...@gmail.com wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. I am currently in the progress of writing a Wayland binding generator for the Rust language. This language, like many others is strongly typed. To make full usage of this type system, it would be beneficial to know from the specification whether an argument is a bitfield, and what enum type it takes. Surely there are more people who generate bindings to these strongly typed languages. How have you fixed the issue? Are there patched versions available, and maybe pending to be merged? I have looked around a bit, and didn't find anything, but then again, I'm not familiar with Wayland development. (This is the first time I use a mailing list!) Much appreciated, Jeroen Bollen ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel Based on the discussion I wrote two patches: one for the wayland.xml (and wayland.dtd since the fact of the matter is that that file is still there), and one for scanner.c See 5dc0112f734d23d65a2bf9a78f11463d0294b6c7 and b6d5659c650056f66267f3f20fdbaf724138a61b in [0]. Is this a good format for sending patches? Or are actual patch emails preferred? The scanner.c code checks that the enum attribute of an arg is the name of an enum in the same interface. In that case, it checks that the type of the arg is an int or a uint, and if the enum had bitfield set to true, that the type was indeed uint. If these properties are not satisfied, the scanner dies. Is that what was expected? Auke. [0] https://github.com/tulcod/wayland/tree/enum-attribute ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
About the 2 ways of adding an enum: The user can always specify an error handler to handle unknown values. The error handle can then handle the error value, or unknown value. On Mon, 27 Apr 2015 09:05 Pekka Paalanen ppaala...@gmail.com wrote: On Sat, 25 Apr 2015 14:11:32 + Jeroen Bollen jbin...@gmail.com wrote: I think that totally depends on how the interface is specified. This applies only to one of the two ways an enum can grow. What other way can it grow? It can only grow bigger. If the application isn't aware of new values added, it should output a warning or an error. These: On Wed, 22 Apr 2015 09:34:51 +0300 Pekka Paalanen ppaala...@gmail.com wrote: There are two ways to add values to an existing enum: - Bumping the interface version, and ensuring the new values are used only with the appropriate runtime interface version. - From the first definition of an interface, specify how unknown values should be handled. Otherwise users do not expect unknown values to appear. The latter case is where you do not want an automatic always-on warning or error. On Fri, 24 Apr 2015 22:05 Bill Spitzak spit...@gmail.com wrote: Since all the codegen packages that want to use this enum attribute have not been written yet I don't think back-compatibility is an issue. They are not using uint because they do not exist yet! Except if you happen to have an old libwayland which you develop your 3rd party app against, for instance because you use a distribution that does not include a more recent version yet. Depending on the language, I suppose the breakage could go both ways? Is there a language where an enum is not allowed to be implicitly converted to a uint or int? Thanks, pq The C codegen can continue to ignore the enum, or use it in a way that does not break code that tries to pass an integer or the wrong enum. On 04/24/2015 12:07 AM, Pekka Paalanen wrote: The purpose of docenum was purely for documentation. An API generator must ignore all docenum annotations. This was the backward-compatible addition. Any attribute that modifies the generated API in incompatible ways cannot be added after the interface has been released as stable. If your function argument was uint, and you change it to an enum in a strictly typed language, does it not have a good chance of breaking someone's build? ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Sat, 25 Apr 2015 14:11:32 + Jeroen Bollen jbin...@gmail.com wrote: I think that totally depends on how the interface is specified. This applies only to one of the two ways an enum can grow. What other way can it grow? It can only grow bigger. If the application isn't aware of new values added, it should output a warning or an error. These: On Wed, 22 Apr 2015 09:34:51 +0300 Pekka Paalanen ppaala...@gmail.com wrote: There are two ways to add values to an existing enum: - Bumping the interface version, and ensuring the new values are used only with the appropriate runtime interface version. - From the first definition of an interface, specify how unknown values should be handled. Otherwise users do not expect unknown values to appear. The latter case is where you do not want an automatic always-on warning or error. On Fri, 24 Apr 2015 22:05 Bill Spitzak spit...@gmail.com wrote: Since all the codegen packages that want to use this enum attribute have not been written yet I don't think back-compatibility is an issue. They are not using uint because they do not exist yet! Except if you happen to have an old libwayland which you develop your 3rd party app against, for instance because you use a distribution that does not include a more recent version yet. Depending on the language, I suppose the breakage could go both ways? Is there a language where an enum is not allowed to be implicitly converted to a uint or int? Thanks, pq The C codegen can continue to ignore the enum, or use it in a way that does not break code that tries to pass an integer or the wrong enum. On 04/24/2015 12:07 AM, Pekka Paalanen wrote: The purpose of docenum was purely for documentation. An API generator must ignore all docenum annotations. This was the backward-compatible addition. Any attribute that modifies the generated API in incompatible ways cannot be added after the interface has been released as stable. If your function argument was uint, and you change it to an enum in a strictly typed language, does it not have a good chance of breaking someone's build? ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On 21 Apr 2015 09:18, Pekka Paalanen ppaala...@gmail.com wrote: Two things I came up with in the IRC discussion was that only arg types of int an uint are eligible for enums, and only uint for bitfields. I think wayland-scanner should enforce that. I just realised another aspect of this. Can a (non-bitfield) enum be used both as an int and a uint? So some *int* argument somewhere has enum=bla, and a *uint* argument somewhere else has enum=bla as well. What about enums that list negative values, can they be used as uints? I feel that this would be extremely prone to bugs, and in fact I think this is a situation where semantic information of enum style arguments can help catch bugs in C code (which so far we haven't seen yet in this debate). Should this be enforced by the scanner? Or is there some crazy situation in which it makes sense? ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, 27 Apr 2015 15:49:27 +0300 Pekka Paalanen ppaala...@gmail.com wrote: 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. How about we just define a new attribute for arg that points to an enum for documentary purposes, and warns if the type is not int/uint or uint for bitfields; and add an attribute to enum to say it's a bitfield instead, without any further enforced restrictions. Then, if you want to generate API bindings that have extra restrictions not warranted by the above, you can. You also get to keep all the pieces if it breaks someone. This would be the documentation-only, but we can't stop you from abusing it solution. The chances are that it would work just fine for 99% of your favourite language's users. We can add the attributes retroactively, and you can write software that requires the version of libwayland or whatever that has these attributes in the XML. The point is, it will be clear on what protocol writers can and cannot do, and with maximum benefits. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On 27 April 2015 at 14:49, Pekka Paalanen ppaala...@gmail.com wrote: On Mon, 27 Apr 2015 13:26:39 +0200 Auke Booij a...@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 ppaala...@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 enums, 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 enums. 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
Re: [PATCH wayland] Add enum attribute to arg elements
Apologies for my lack of responses, I have been abroad for a few days. On 23 April 2015 at 10:38, Pekka Paalanen ppaala...@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). (*) 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. 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? 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 enums, 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 enums. 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). - 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. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
In fact, I am still a bit confused why an API breakage in these early years of wayland is considered such a big deal, compared with a daily struggle of not having sufficient typing information. Same here To pq: If an request specifies how unknown enum values should be handled, it just specifies an error handler. If the request is meant to run with enums, then the enums serve no point anyway. In such a case, I wouldn't even have it say it takes an enum. It should just say it takes a uint, and the enum should say its value is uint. Preferably, the element wouldn't even be an enum, because all it does is listing meaningless values. On Mon, 27 Apr 2015 at 15:20 Auke Booij a...@tulcod.com wrote: On 27 April 2015 at 14:49, Pekka Paalanen ppaala...@gmail.com wrote: On Mon, 27 Apr 2015 13:26:39 +0200 Auke Booij a...@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 ppaala...@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
Re: [PATCH wayland] Add enum attribute to arg elements
On 04/27/2015 12:05 AM, Pekka Paalanen wrote: - From the first definition of an interface, specify how unknown values should be handled. Otherwise users do not expect unknown values to appear. The latter case is where you do not want an automatic always-on warning or error. This is no problem. The caller has to do a cast, ie EnumName(43), to get this value. I am pretty certain users of strongly-typed languages do not expect a raw 43 to work and are quite willing to do the cast. I suppose you could purposely prevent the cast from working on final enuerations, but that is usually just frustrating to programmers that will need it some times, even if they know they are only generating valid values. In particular it may make it difficult to implement one api atop another. Except if you happen to have an old libwayland which you develop your 3rd party app against, for instance because you use a distribution that does not include a more recent version yet. The enum part of the protocol has zero effect on the implementation or abi of libwayland. At the point functions are called in libwayland they have already been turned into int/uint. If the arguments to the C abi were changed to C enums instead of int/uint it would break things. However I think the proposal is to use the enums in minimal ways in the C abi. Depending on the language, I suppose the breakage could go both ways? Is there a language where an enum is not allowed to be implicitly converted to a uint or int? Yes lots of them. However this is irrelevant because the binding code will be changing them to int/uint in some way. Eventually it has to stuff the value into the Wayland byte stream and that code certainly will be thinking about int/uint. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
I think that totally depends on how the interface is specified. This applies only to one of the two ways an enum can grow. What other way can it grow? It can only grow bigger. If the application isn't aware of new values added, it should output a warning or an error. On Fri, 24 Apr 2015 22:05 Bill Spitzak spit...@gmail.com wrote: Since all the codegen packages that want to use this enum attribute have not been written yet I don't think back-compatibility is an issue. They are not using uint because they do not exist yet! The C codegen can continue to ignore the enum, or use it in a way that does not break code that tries to pass an integer or the wrong enum. On 04/24/2015 12:07 AM, Pekka Paalanen wrote: The purpose of docenum was purely for documentation. An API generator must ignore all docenum annotations. This was the backward-compatible addition. Any attribute that modifies the generated API in incompatible ways cannot be added after the interface has been released as stable. If your function argument was uint, and you change it to an enum in a strictly typed language, does it not have a good chance of breaking someone's build? ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Thu, 23 Apr 2015 10:44:50 -0700 Bill Spitzak spit...@gmail.com wrote: On 04/22/2015 11:38 PM, Pekka Paalanen wrote: Given this and that they must not affect codegen, what are the remaining differences between enums and bitfields? Enum can be an int, but a bitfield cannot? Is it worth to have the distinction in the language at all? The distinction is that in a bitfield A|B is valid value to pass, but that is not a valid value to pass for an enumeration. Bindings really want this information. If you say that, you again imply that the annotation must affect codegen (the generated API). The question explicitly assumed it must not affect codegen. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Thu, 23 Apr 2015 14:45:32 + Jeroen Bollen jbin...@gmail.com wrote: Hello, I do think that docenum and enum should be split up. I don't really get the purpose of docenum though. Even if an enum can be extended, that extension would technically be an extension to the protocol, would it not? I listed the two (three) ways you can reasonably add new values to an enum in this thread. The purpose of docenum was purely for documentation. An API generator must ignore all docenum annotations. This was the backward-compatible addition. Any attribute that modifies the generated API in incompatible ways cannot be added after the interface has been released as stable. If your function argument was uint, and you change it to an enum in a strictly typed language, does it not have a good chance of breaking someone's build? Think about distributions. A packager goes and upgrades the libwayland package, which installs a new wayland.xml with strict type annotations added. Your code generator starts using these annotation and the generated API changes. A third party application fails to build from source because of API mismatch. The packager becomes very unhappy. Completeness of enums is information that can be encoded in strongly typed languages, but I do not think such guarantees are necessary. Bindings should be able to deal with new constants not listed in the protocol. If we guarantee completeness of enums, I expect we will get all kinds of backwards compatibility issues. Did I write this? I can't find the source of this quotation... I do not quite agree with this. If an application encounters an enum it's not familiar with, it should output a warning or an error. The bindings should generate the code to be used by the application. If the application wants to extend the protocol, they'll have to extend the specification. I think that totally depends on how the interface is specified. This applies only to one of the two ways an enum can grow. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
Since all the codegen packages that want to use this enum attribute have not been written yet I don't think back-compatibility is an issue. They are not using uint because they do not exist yet! The C codegen can continue to ignore the enum, or use it in a way that does not break code that tries to pass an integer or the wrong enum. On 04/24/2015 12:07 AM, Pekka Paalanen wrote: The purpose of docenum was purely for documentation. An API generator must ignore all docenum annotations. This was the backward-compatible addition. Any attribute that modifies the generated API in incompatible ways cannot be added after the interface has been released as stable. If your function argument was uint, and you change it to an enum in a strictly typed language, does it not have a good chance of breaking someone's build? ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
Hello, I do think that docenum and enum should be split up. I don't really get the purpose of docenum though. Even if an enum can be extended, that extension would technically be an extension to the protocol, would it not? Completeness of enums is information that can be encoded in strongly typed languages, but I do not think such guarantees are necessary. Bindings should be able to deal with new constants not listed in the protocol. If we guarantee completeness of enums, I expect we will get all kinds of backwards compatibility issues. I do not quite agree with this. If an application encounters an enum it's not familiar with, it should output a warning or an error. The bindings should generate the code to be used by the application. If the application wants to extend the protocol, they'll have to extend the specification. As for the bitfields, I do agree it makes more sense to have them in the argument tags, for the reasons already mentioned. That would be solved by documenting the XML language, including guidelines for generator writers. I think there are things that wayland-scanner cannot communicate, especially when they do not really exist in C. I can only agree with this. Thanks - Jeroen On Thu, 23 Apr 2015 at 10:38 Pekka Paalanen ppaala...@gmail.com wrote: On Thu, 23 Apr 2015 10:17:12 +0200 Auke Booij a...@tulcod.com wrote: On 23 April 2015 at 08:38, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 22 Apr 2015 11:47:51 +0200 Auke Booij a...@tulcod.com wrote: On 22 April 2015 at 08:34, Pekka Paalanen ppaala...@gmail.com wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one (ignore, use as a literal value, ...). Wayland-scanner would generate the doclink references in header comments, and check that the referenced enum exists and the arg type. Two comments on this. 1. I do not think it is necessary to distinguish between docenum and enumeration. At least for me, I am not asking for any new guarantees with regards to completeness: sure, new constants may be added on the fly. All I want is semantic information: which (u)int refers to which enum? And this data would be provided by your docenum (which I would just call enum). Jeroen seemed to be wanting that. That's why it gets complicated. I agree. Well, if there is support for Jeroen's ideas, I will add that to the scanner.c patch. I am not against them, but I would expect the guarantees to be broken by C code all the time, so there needs to be a solution for that. I'd rather not, or at least separate these two. We can add the doc attribute, and discuss the strictness later. Adding strictness constraints later should be as simple as adding more attributes. However, if strictness attributes affect codegen, it might be difficult to add them to existing enums, because it would change the API a code generator produces. That is a pretty strong reason to not change anything that affects codegen: you may be using an XML file that does not have these attributes, or you may be using a generator that does not handle these attributes. Third party XML files are a thing,
Re: [PATCH wayland] Add enum attribute to arg elements
On 04/22/2015 11:49 PM, Pekka Paalanen wrote: Allowing fully qualified names is another thing. Should we allow it? Is it good practice? Is it useful? How would the fully qualitified names look like? Even if it's not used for codegen, you need it for docgen if you want to be able to reference other interfaces' enums. Many interfaces may have same-named enums. Using enum=interfacename.enumname would probably work. The interfacename. is optional if you are describing a method on the same interface. Another possibility is to just add interface=interfacename to the argument along with enum=enumname. Due to the name collisions of both enum names and enum values, most language binding will probably have to fully qualify any values. So you are likely to see widget.setAlignment(Widget.Align.Left) despite the redundant information. So a more drastic approach might be to make enums be in the same namespace as interfaces, renaming them as necessary to avoid collisions. An even more drastic approach would be to put all the values in the same namespace as interfaces, again renaming (or perhaps changing the values) as necessary. This would allow the programmer to write Widget.setAlignment(Left). It would also match how enums in C work. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
Using enum=interfacename.enumname would probably work. The interfacename. is optional if you are describing a method on the same interface. Another possibility is to just add interface=interfacename to the argument along with enum=enumname. The second possibility wouldn't work for bitfields that take enums from different interfaces. An even more drastic approach would be to put all the values in the same namespace as interfaces, again renaming (or perhaps changing the values) as necessary. This would allow the programmer to write Widget.setAlignment(Left). It would also match how enums in C work. Putting enums next to interfaces, instead of inside of them, to me, also seems like the best option. I don't think it'll get any support however, as it isn't backwards compatible. On Thu, 23 Apr 2015 at 20:22 Bill Spitzak spit...@gmail.com wrote: On 04/22/2015 11:49 PM, Pekka Paalanen wrote: Allowing fully qualified names is another thing. Should we allow it? Is it good practice? Is it useful? How would the fully qualitified names look like? Even if it's not used for codegen, you need it for docgen if you want to be able to reference other interfaces' enums. Many interfaces may have same-named enums. Using enum=interfacename.enumname would probably work. The interfacename. is optional if you are describing a method on the same interface. Another possibility is to just add interface=interfacename to the argument along with enum=enumname. Due to the name collisions of both enum names and enum values, most language binding will probably have to fully qualify any values. So you are likely to see widget.setAlignment(Widget.Align.Left) despite the redundant information. So a more drastic approach might be to make enums be in the same namespace as interfaces, renaming them as necessary to avoid collisions. An even more drastic approach would be to put all the values in the same namespace as interfaces, again renaming (or perhaps changing the values) as necessary. This would allow the programmer to write Widget.setAlignment(Left). It would also match how enums in C work. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
(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). I do not quite agree with this. Yes, they should know they are wading into dangerous waters, but any error that can be prevented, should be. It also helps of course, for features like code completion, although as I am writing Rust bindings, that doesn't apply to me. Maybe it could be added, ie you can make global enumerations as well as local enumerations. Local ones are still useful for the error values. That would be a good solution, but maybe that's making the specification a bit too complex? I would be in favour of moving everything to same namespace as the interface, but of course, compatibility issues will arise with exciting binding generators. In any case, I think the specification should be as strict as possible, because making it stricter is hard, but making it less strict is easy. On Thu, 23 Apr 2015 at 20:59 Bill Spitzak spit...@gmail.com wrote: On 04/23/2015 11:28 AM, Jeroen Bollen wrote: Using enum=interfacename.enumname would probably work. The interfacename. is optional if you are describing a method on the same interface. Another possibility is to just add interface=interfacename to the argument along with enum=enumname. The second possibility wouldn't work for bitfields that take enums from different interfaces. I didn't think that would be allowed. The bitmap arg can only or together a set of values from a single enumeration. An even more drastic approach would be to put all the values in the same namespace as interfaces, again renaming (or perhaps changing the values) as necessary. This would allow the programmer to write Widget.setAlignment(Left). It would also match how enums in C work. Putting enums next to interfaces, instead of inside of them, to me, also seems like the best option. I don't think it'll get any support however, as it isn't backwards compatible. Maybe it could be added, ie you can make global enumerations as well as local enumerations. Local ones are still useful for the error values. Some sort of aliasing could be used to migrate other local enumerations to global without breaking any existing code. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
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: widget.set_type(Widget.Type.Left) widget.set_flags(Widget.Flags.A) 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: widget.set_type(Widget.Type(43)) widget.set_flags(Widget.Flags(0x1349)) (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; // *** widget.set_flags(x) 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. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On 04/23/2015 11:28 AM, Jeroen Bollen wrote: Using enum=interfacename.enumname would probably work. The interfacename. is optional if you are describing a method on the same interface. Another possibility is to just add interface=interfacename to the argument along with enum=enumname. The second possibility wouldn't work for bitfields that take enums from different interfaces. I didn't think that would be allowed. The bitmap arg can only or together a set of values from a single enumeration. An even more drastic approach would be to put all the values in the same namespace as interfaces, again renaming (or perhaps changing the values) as necessary. This would allow the programmer to write Widget.setAlignment(Left). It would also match how enums in C work. Putting enums next to interfaces, instead of inside of them, to me, also seems like the best option. I don't think it'll get any support however, as it isn't backwards compatible. Maybe it could be added, ie you can make global enumerations as well as local enumerations. Local ones are still useful for the error values. Some sort of aliasing could be used to migrate other local enumerations to global without breaking any existing code. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Wed, 22 Apr 2015 08:38:22 -0700 Bill Spitzak spit...@gmail.com wrote: On 04/21/2015 11:34 PM, Pekka Paalanen wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. Absolutely agree How about this: Auke's original patch is much more like what is wanted. Yeah, it mostly just lacked a clear explanation on what the new attributes mean. It seems Auke and Jeroen had quite different interpretations and goals. However, a remaining problem is that an interface cannot reference an enum defined for a different interface. You can reference objects defined by a different interface, right? I don't think this is any different. Objects work because you know they are represented by an id. For many languages the code generation does not depend on the details of the enumeration, it just needs to know it's name, so there is no need to parse the other file. And whether int or uint is in the api, but that information is already there. Sure, by the interface name. However, I assumed the new attribute would refer to an enum by it's short name, not a fully qualified name that includes the interface name. Allowing fully qualified names is another thing. Should we allow it? Is it good practice? Is it useful? How would the fully qualitified names look like? Even if it's not used for codegen, you need it for docgen if you want to be able to reference other interfaces' enums. Many interfaces may have same-named enums. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Wed, 22 Apr 2015 11:47:51 +0200 Auke Booij a...@tulcod.com wrote: On 22 April 2015 at 08:34, Pekka Paalanen ppaala...@gmail.com wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one (ignore, use as a literal value, ...). Wayland-scanner would generate the doclink references in header comments, and check that the referenced enum exists and the arg type. Two comments on this. 1. I do not think it is necessary to distinguish between docenum and enumeration. At least for me, I am not asking for any new guarantees with regards to completeness: sure, new constants may be added on the fly. All I want is semantic information: which (u)int refers to which enum? And this data would be provided by your docenum (which I would just call enum). Jeroen seemed to be wanting that. That's why it gets complicated. It also wasn't clear as your patch didn't have a good explanation on what the attributes really mean. Explaining them is the most important part of a patch, especially how it may affect codegen (or in this case, must not affect codegen). Completeness of enums is information that can be encoded in strongly typed languages, but I do not think such guarantees are necessary. Bindings should be able to deal with new constants not listed in the protocol. If we guarantee completeness of enums, I expect we will get all kinds of backwards compatibility issues. Nice to hear. 2. I would say the property of being a bitfield belongs to an enum, not to an argument: the type that is generated corresponds to an enum, not to an argument. And as such, the properties of this type should not depend on the argument's attributes. So I would say the bitfield attribute should go in the enum. Otherwise, what is meant if one argument uses an enum as a bitfield, and another argument uses the same enum as a regular enum? Okay. I agree that it should express that OR'ing together any number of values from the list should *at least* not be considered a protocol error. They may still be disregarded for other reasons, but passing OR'ed values in a bitfield should not break protocol, and this is the guarantee a bitfield flag should express (IMO). I'm not sure about that. The allowance to or things together was more related to the strict enumeration enforcement. Interfaces should be able to still say, that a certain combination is illegal and will lead to a protocol error. None of it will ever break protocol on the wire level, as it is all just uints. Given this and that they must not affect codegen, what are the remaining differences between enums and bitfields? Enum can be an int, but a bitfield cannot? Is it worth to have the distinction in the language at all? In the end, is the only really useful thing left the doc linking? It seems the main difference between your and Jeroen's requirements is that Jeroen wants strict guarantees so that codegen can generate the strictest APIs in his language. However, a remaining problem is that an interface cannot reference an enum defined for a different interface. That is a special case I don't know if we should support in this scheme, because it would require the depended-on XML file to be used during parsing, and we do not require that for
Re: [PATCH wayland] Add enum attribute to arg elements
On Thu, 23 Apr 2015 10:17:12 +0200 Auke Booij a...@tulcod.com wrote: On 23 April 2015 at 08:38, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 22 Apr 2015 11:47:51 +0200 Auke Booij a...@tulcod.com wrote: On 22 April 2015 at 08:34, Pekka Paalanen ppaala...@gmail.com wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one (ignore, use as a literal value, ...). Wayland-scanner would generate the doclink references in header comments, and check that the referenced enum exists and the arg type. Two comments on this. 1. I do not think it is necessary to distinguish between docenum and enumeration. At least for me, I am not asking for any new guarantees with regards to completeness: sure, new constants may be added on the fly. All I want is semantic information: which (u)int refers to which enum? And this data would be provided by your docenum (which I would just call enum). Jeroen seemed to be wanting that. That's why it gets complicated. I agree. Well, if there is support for Jeroen's ideas, I will add that to the scanner.c patch. I am not against them, but I would expect the guarantees to be broken by C code all the time, so there needs to be a solution for that. I'd rather not, or at least separate these two. We can add the doc attribute, and discuss the strictness later. Adding strictness constraints later should be as simple as adding more attributes. However, if strictness attributes affect codegen, it might be difficult to add them to existing enums, because it would change the API a code generator produces. That is a pretty strong reason to not change anything that affects codegen: you may be using an XML file that does not have these attributes, or you may be using a generator that does not handle these attributes. Third party XML files are a thing, you don't have control over everything. Version requirements on depended-on projects could be used to mitigate it, plus perhaps a switch to the generator to ignore the new attributes until your code ports to the strictly typed API. I agree that it should express that OR'ing together any number of values from the list should *at least* not be considered a protocol error. They may still be disregarded for other reasons, but passing OR'ed values in a bitfield should not break protocol, and this is the guarantee a bitfield flag should express (IMO). I'm not sure about that. The allowance to or things together was more related to the strict enumeration enforcement. Interfaces should be able to still say, that a certain combination is illegal and will lead to a protocol error. None of it will ever break protocol on the wire level, as it is all just uints. Given this and that they must not affect codegen, what are the remaining differences between enums and bitfields? Enum can be an int, but a bitfield cannot? Is it worth to have the distinction in the language at all? In the end, is the only really useful thing left the doc linking? Well, for one, there is a semantic difference, which in richly typed languages is not to be underestimated. Perhaps the requirement should be that: at least one (non-empty) combination of listed values
Re: [PATCH wayland] Add enum attribute to arg elements
On 23 April 2015 at 08:38, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 22 Apr 2015 11:47:51 +0200 Auke Booij a...@tulcod.com wrote: On 22 April 2015 at 08:34, Pekka Paalanen ppaala...@gmail.com wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one (ignore, use as a literal value, ...). Wayland-scanner would generate the doclink references in header comments, and check that the referenced enum exists and the arg type. Two comments on this. 1. I do not think it is necessary to distinguish between docenum and enumeration. At least for me, I am not asking for any new guarantees with regards to completeness: sure, new constants may be added on the fly. All I want is semantic information: which (u)int refers to which enum? And this data would be provided by your docenum (which I would just call enum). Jeroen seemed to be wanting that. That's why it gets complicated. I agree. Well, if there is support for Jeroen's ideas, I will add that to the scanner.c patch. I am not against them, but I would expect the guarantees to be broken by C code all the time, so there needs to be a solution for that. I agree that it should express that OR'ing together any number of values from the list should *at least* not be considered a protocol error. They may still be disregarded for other reasons, but passing OR'ed values in a bitfield should not break protocol, and this is the guarantee a bitfield flag should express (IMO). I'm not sure about that. The allowance to or things together was more related to the strict enumeration enforcement. Interfaces should be able to still say, that a certain combination is illegal and will lead to a protocol error. None of it will ever break protocol on the wire level, as it is all just uints. Given this and that they must not affect codegen, what are the remaining differences between enums and bitfields? Enum can be an int, but a bitfield cannot? Is it worth to have the distinction in the language at all? In the end, is the only really useful thing left the doc linking? Well, for one, there is a semantic difference, which in richly typed languages is not to be underestimated. Perhaps the requirement should be that: at least one (non-empty) combination of listed values OR'ed together results in a new valid value (ie one not listed) 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. It seems the main difference between your and Jeroen's requirements is that Jeroen wants strict guarantees so that codegen can generate the strictest APIs in his language. I agree. Like I said, such guarantees are welcome, as long as the situation is also clear for C, so that we don't get any annoying incompatibilities due to misunderstandings between languages. At this point I am not asking for them. I fixed Bill's note on my sample patch, and will publish my intermediary work on my github [0] (probably this will be limited to just two commits, but you can subscribe if you want to). [0] https://github.com/tulcod/wayland/tree/enum-attribute ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org
Re: [PATCH wayland] Add enum attribute to arg elements
On Tue, 21 Apr 2015 16:32:40 + Jeroen Bollen jbin...@gmail.com wrote: I think I have thought out a solution. The scanner should be able to parse multiple specification files. There would be the default wayland.xml, and for example a gnome.xml, which is an extension to the wayland.xml. It does only contain things like added interfaces, added requests, added events and added enum variants. The scanner would merge all these files together. You cannot add events or requests to existing interfaces without requiring the world to always use exactly the same aggregate set of xml files. It is much simpler to just extend existing interfaces properly, in the xml file they are defined in in the first place. That way you can also do the proper versioning, and people are not surprised by that using only wayland.xml breaks things. This is not a tractable approach. The fundamental reason for this is how we assign message opcodes. Adding interfaces is simple, you don't need to parse several XML files in one go to do that. Unless your specific language and generator simply cannot work otherwise, but that is your problem. Mind, that people probably want to use specific protocol extensions in modules (whatever those are in your language), so would be really nice to not deny them from that. If your generator requires also all the dependant XML files to be present when parsing a new XML file, I think that would be fine. But I do not think making it a generic mechanism to extend existing interfaces is an idea that could work. Adding values to existing enum sets in additional XML files is less prone to break, but still not a good idea. You will be splitting the value allocations to several places, which requires careful coordination to avoid clashes. It doesn't feel like a good idea to me to support this generally for everything. There are two ways to add values to an existing enum: - Bumping the interface version, and ensuring the new values are used only with the appropriate runtime interface version. - From the first definition of an interface, specify how unknown values should be handled. Otherwise users do not expect unknown values to appear. The third case is error enums. IMO, error codes can be added without any special care, because a protocol error event which carries these is always fatal anyway. They always terminate the Wayland connection, so there is nothing a client could do afterwards apart from just reporting the error. This means that enums can be complete. If a user wants to have additional values, they should simply add an XML for the extended feature set. This would also reduce and fragmentation, as extensions to the protocol don't require one to maintain an entire wayland.xml file anymore. It also allows people to use multiple protocol extensions at once, without merging multiple, already-forked specifications. What are the opinions on this? I didn't think anyone was maintaining modified wayland.xml files. It would certainly be very fragile and break interoperability between projects. Feature development is one thing, but releasing a project with a modified wayland.xml seems as good as providing your own modified versions of libc headers. I see it as asking for trouble and quite likely succeeding. I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one
Re: [PATCH wayland] Add enum attribute to arg elements
I think this looks like the correct patch. Only correction is that I would put the enum right after the type=int consistently. Some of your cases you put the summary between them. On 04/19/2015 01:30 PM, Auke Booij wrote: On 19 April 2015 at 14:51, Jeroen Bollen jbin...@gmail.com wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. I am currently in the progress of writing a Wayland binding generator for the Rust language. This language, like many others is strongly typed. To make full usage of this type system, it would be beneficial to know from the specification whether an argument is a bitfield, and what enum type it takes. Surely there are more people who generate bindings to these strongly typed languages. How have you fixed the issue? Are there patched versions available, and maybe pending to be merged? I have looked around a bit, and didn't find anything, but then again, I'm not familiar with Wayland development. (This is the first time I use a mailing list!) Quite coincidentally, I was planning on writing a similar email quite soon, so I'll just go ahead and write what I wanted to say! I wrote Haskell bindings, and the same problem occurs there. I did not find a way to solve the problem, and it would be best if such an enum argument be added to the spec. I wrote the patch below. It introduces an enum attribute that allows message arguments to refer to the enum collection they're using (it is understood that this enum is part of the same interface). I also added a bitfield attribute to enums that indicates whether the enum values are to be OR'ed together, or to be used as-is: ie whether the enum values are actually enums or actually flag fields. This improvement to the protocol allows you to refer to the kind of enum you are expecting. It also introduces a distinction between enums that are bitfields, ie that can be OR'ed together. --- protocol/wayland.dtd | 2 ++ protocol/wayland.xml | 32 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/protocol/wayland.dtd b/protocol/wayland.dtd index b8b1573..3b67ca8 100644 --- a/protocol/wayland.dtd +++ b/protocol/wayland.dtd @@ -14,6 +14,7 @@ !ELEMENT enum (description?,entry*) !ATTLIST enum name CDATA #REQUIRED !ATTLIST enum since CDATA #IMPLIED + !ATTLIST enum bitfield CDATA #IMPLIED !ELEMENT entry (description?) !ATTLIST entry name CDATA #REQUIRED !ATTLIST entry value CDATA #REQUIRED @@ -25,5 +26,6 @@ !ATTLIST arg summary CDATA #IMPLIED !ATTLIST arg interface CDATA #IMPLIED !ATTLIST arg allow-null CDATA #IMPLIED + !ATTLIST arg enum CDATA #IMPLIED !ELEMENT description (#PCDATA) !ATTLIST description summary CDATA #REQUIRED diff --git a/protocol/wayland.xml b/protocol/wayland.xml index f52677f..2b9efa1 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -367,7 +367,7 @@ can be used for buffers. Known formats include argb and xrgb. /description - arg name=format type=uint/ + arg name=format type=uint enum=format/ /event /interface @@ -774,7 +774,7 @@ /description arg name=seat type=object interface=wl_seat summary=the wl_seat whose pointer is used/ arg name=serial type=uint summary=serial of the implicit grab on the pointer/ - arg name=edges type=uint summary=which edge or corner is being dragged/ + arg name=edges type=uint summary=which edge or corner is being dragged enum=resize/ /request request name=set_toplevel @@ -785,7 +785,7 @@ /description /request -enum name=transient +enum name=transient bitfield=true description summary=details of transient behaviour These flags specify details of the expected behaviour of transient surfaces. Used in the set_transient request. @@ -807,7 +807,7 @@ arg name=parent type=object interface=wl_surface/ arg name=x type=int/ arg name=y type=int/ - arg name=flags type=uint/ + arg name=flags type=uint enum=transient/ /request enum name=fullscreen_method @@ -891,7 +891,7 @@ arg name=parent type=object interface=wl_surface/ arg name=x type=int/ arg name=y type=int/ - arg name=flags type=uint/ + arg name=flags type=uint enum=transient/ /request request name=set_maximized @@ -972,7 +972,7 @@ in surface local coordinates. /description - arg name=edges type=uint/ + arg name=edges type=uint enum=resize/ arg name=width type=int/ arg name=height type=int/ /event @@ -1337,7 +1337,7 @@ maintains a keyboard focus and a pointer focus. /description -enum name=capability +enum name=capability bitfield=true description summary=seat capability bitmask This
Re: [PATCH wayland] Add enum attribute to arg elements
On 22 April 2015 at 08:34, Pekka Paalanen ppaala...@gmail.com wrote: I also think this discussion is going off-topic. You wanted to add annotations to the XML, so you could find out about enum and bitfield arguments, so let's keep to that. There is value in simplicity. How about this: Add three new, mutually exclusive attributes for arg tags: docenum=enumname Docenum would be for documentation linking only, and should not affect code generation. The effect would be in the documentation to add a link to the definition of the enumname enum. This attribute is applicable for both int and uint type args. enumeration=enumname Enumeration would be a doc link, but also specify that the enum enumname is a complete enumeration: no other values are legal. You can use this for code generation. You will rely on interface version negotiation to avoid unknown values in case you have an old definition of the interface and your opponent is using a new definition which added values. This attribute is applicable for both int and uint type args. bitfield=enumname Bitfield would be a doc link, but also specify that the values listed in enum enumanme can be orred together to form new legal values. Bits that are not settable by using the listed values must be zero. You rely on the interface versioning to avoid getting undefined bits set, just like enumeration relies for adding new values. This attribute is applicable only to uint type args. So, both enumeration and bitfield could be used for codegen, docenum would not. Docenum or nothing would be used for cases that do not fit as enumeration or bitfield, including cases where unknown values are always allowed but the interface specification defines what to do when encountering one (ignore, use as a literal value, ...). Wayland-scanner would generate the doclink references in header comments, and check that the referenced enum exists and the arg type. Two comments on this. 1. I do not think it is necessary to distinguish between docenum and enumeration. At least for me, I am not asking for any new guarantees with regards to completeness: sure, new constants may be added on the fly. All I want is semantic information: which (u)int refers to which enum? And this data would be provided by your docenum (which I would just call enum). Completeness of enums is information that can be encoded in strongly typed languages, but I do not think such guarantees are necessary. Bindings should be able to deal with new constants not listed in the protocol. If we guarantee completeness of enums, I expect we will get all kinds of backwards compatibility issues. 2. I would say the property of being a bitfield belongs to an enum, not to an argument: the type that is generated corresponds to an enum, not to an argument. And as such, the properties of this type should not depend on the argument's attributes. So I would say the bitfield attribute should go in the enum. Otherwise, what is meant if one argument uses an enum as a bitfield, and another argument uses the same enum as a regular enum? I agree that it should express that OR'ing together any number of values from the list should *at least* not be considered a protocol error. They may still be disregarded for other reasons, but passing OR'ed values in a bitfield should not break protocol, and this is the guarantee a bitfield flag should express (IMO). However, a remaining problem is that an interface cannot reference an enum defined for a different interface. That is a special case I don't know if we should support in this scheme, because it would require the depended-on XML file to be used during parsing, and we do not require that for wayland-scanner. So I'd rather leave that special case for pure documentation and no attribute, at least for now. Developing a way to reference external interfaces is for another time. I agree. All that said, this is just a quick draft I haven't really thought through. You could name the attributes differently, change docenum to be an attribute for description rather than arg, etc. I will see if I can write a wayland-scanner patch for the above ideas, so that we all know what we're talking about. Thanks, pq Thanks to you for listening and taking these ideas seriously! ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, 20 Apr 2015 15:54:59 + Jeroen Bollen jbin...@gmail.com wrote: On Mon, 20 Apr 2015 at 09:03 Pekka Paalanen ppaala...@gmail.com wrote: Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. This and all the above are the likely reasons why adding the strict type information is not interesting, at least for me. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? So, the big question here is: do we even want to have strict enum types? It does indeed not provide any benefit for C, but if C is the only language to be targeted, there is not much use in there being an XML specification at all. It could've just been written out in C. I do agree that any changes should be compatible with C. I know in Rust, conversion from the `uint` to the `enum` type would have to be done manually, and error checking happens here. It does stop the user from passing illegal values to other servers however. It also makes it more clear what `enum`s are to be used with which arguments, and enforces this. I don't really see why adding that to the specification is an issue. If some `enum` types aren't complete, as in, they aren't the only valid values, then I see little value in having the `enum` in the specification in the first place. The foremost purpose of the enum is to let the generator create named constants in a namespace. This is something that has to stay due to API stability guarantees. I had some discussion in IRC, and I'm coming around. It does seem a useful addition, but you have to be clear in specifying what it all means. For instance, saying an attribute referencing an enum in an arg for purely documentation linkage would be fine. We don't have docs for the XML language, but at least define it in a commit message. If such annotation is intended to be useful for code generation on relevant languages, you need to define clearly what it means. I'm not familiar with those languages you are interested in, so I cannot judge that. What I would want, is patches to wayland-scanner to use these additional annotations, if only for syntax checking the XML and maybe generating one more comment for an arg or whatever. Unfortunately wayland-scanner still is the definition of the Wayland XML language. It should be kept updated in any case. Two things I came up with in the IRC discussion was that only arg types of int an uint are eligible for enums, and only uint for bitfields. I think wayland-scanner should enforce that. One question was about whether bitfield values should be limited to single bits (powers of two). I think that would be an artificial restriction, and it would not allow using short-hand names for sets of bits. I see no reason to deny those. Another is the question about incomplete enumerations. I don't think we can deny their existence. Therefore they must be supported. If that means you cannot put the enum attribute in such an arg, then so be it; but you lose also the doc linkage. Extending value or bit enumerations is something that happens, and with the expectation that it doesn't break anything. An interface that expects to see new entries in an enumeration in the future will specify how unknown values should be dealt with. You maybe have your code generated according to an old specification, while the other party is using a new specification, and you need to obey the interface specification regarding unknown values. This has to work. Btw. the wayland.dtd is abandoned. The rationale was that if it catches errors that wayland-scanner doesn't, then wayland-scanner should be fixed. We should probably remove that file, and preferably replace it with documentation that agrees with wayland-scanner. If only had the time... Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
I think I have thought out a solution. The scanner should be able to parse multiple specification files. There would be the default wayland.xml, and for example a gnome.xml, which is an extension to the wayland.xml. It does only contain things like added interfaces, added requests, added events and added enum variants. The scanner would merge all these files together. This means that enums can be complete. If a user wants to have additional values, they should simply add an XML for the extended feature set. This would also reduce and fragmentation, as extensions to the protocol don't require one to maintain an entire wayland.xml file anymore. It also allows people to use multiple protocol extensions at once, without merging multiple, already-forked specifications. What are the opinions on this? On Tue, 21 Apr 2015 at 09:18 Pekka Paalanen ppaala...@gmail.com wrote: On Mon, 20 Apr 2015 15:54:59 + Jeroen Bollen jbin...@gmail.com wrote: On Mon, 20 Apr 2015 at 09:03 Pekka Paalanen ppaala...@gmail.com wrote: Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. This and all the above are the likely reasons why adding the strict type information is not interesting, at least for me. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? So, the big question here is: do we even want to have strict enum types? It does indeed not provide any benefit for C, but if C is the only language to be targeted, there is not much use in there being an XML specification at all. It could've just been written out in C. I do agree that any changes should be compatible with C. I know in Rust, conversion from the `uint` to the `enum` type would have to be done manually, and error checking happens here. It does stop the user from passing illegal values to other servers however. It also makes it more clear what `enum`s are to be used with which arguments, and enforces this. I don't really see why adding that to the specification is an issue. If some `enum` types aren't complete, as in, they aren't the only valid values, then I see little value in having the `enum` in the specification in the first place. The foremost purpose of the enum is to let the generator create named constants in a namespace. This is something that has to stay due to API stability guarantees. I had some discussion in IRC, and I'm coming around. It does seem a useful addition, but you have to be clear in specifying what it all means. For instance, saying an attribute referencing an enum in an arg for purely documentation linkage would be fine. We don't have docs for the XML language, but at least define it in a commit message. If such annotation is intended to be useful for code generation on relevant languages, you need to define clearly what it means. I'm not familiar with those languages you are interested in, so I cannot judge that. What I would want, is patches to wayland-scanner to use these additional annotations, if only for syntax checking the XML and maybe generating one more comment for an arg or whatever. Unfortunately wayland-scanner still is the definition of the Wayland XML language. It should be kept updated in any case. Two things I came up with in the IRC discussion was that only arg types of int an uint are eligible for enums, and only uint for bitfields. I think wayland-scanner should enforce that. One question was about whether bitfield values should be limited to single bits (powers of two). I think that would be an artificial restriction, and it would not allow using short-hand names for sets of bits. I see no reason to deny those. Another is the question about incomplete enumerations. I don't think we can deny their existence. Therefore they must be supported. If that means you cannot put the enum attribute in such an arg, then so be it; but you lose also the doc linkage. Extending value or bit enumerations is something that happens, and with the expectation that it doesn't break anything. An interface that expects to see new entries in an enumeration in the future will specify how unknown values should be dealt with. You maybe have your code generated according to an old specification, while the other party is using a new specification, and you need to obey the interface specification regarding unknown values. This has to work.
Re: [PATCH wayland] Add enum attribute to arg elements
Even the patches I did to the automatic documentation generation would benefit greatly from this. There could be a clickable link from the argument to the enumeration, or (with a good deal more work) it could detect enums that are used only once and place them right there under the arg. And it would be nice to format the bitfields a bit differently. The numerical values are more important and printing them is hex is useful, while this is not true for normal enums. On 04/19/2015 05:51 AM, Jeroen Bollen wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. I am currently in the progress of writing a Wayland binding generator for the Rust language. This language, like many others is strongly typed. To make full usage of this type system, it would be beneficial to know from the specification whether an argument is a bitfield, and what enum type it takes. Surely there are more people who generate bindings to these strongly typed languages. How have you fixed the issue? Are there patched versions available, and maybe pending to be merged? I have looked around a bit, and didn't find anything, but then again, I'm not familiar with Wayland development. (This is the first time I use a mailing list!) Much appreciated, Jeroen Bollen ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On 20 April 2015 at 09:03, Pekka Paalanen ppaala...@gmail.com wrote: Hi, Thanks for taking the time to respond. I'll address your issues one by one, but the overarching picture is that such typing information should and would not be interpreted by bindings as a promise, but rather as a hint. I'm starting to think that using the name enum may have been a minor mistake. We are using it to define namespaced constants in the XML files, similar to how you use #define in C with some naming conventions. True, we use the enum type defitions to define these constants in C rather than #defines. I'm not sure if that has any more rationale behind it than it was convenient and allows debuggers to explain the values when cast to the enum type. Nothing guarantees, that an enum element strictly describes a complete enumeration or even a bitfield. You can have entries which contain several bits of a bitfield. You don't have to list all allowed entries, and so on. You could even have an enum that lists only special values and then say a set of other values are allowed, e.g. list some negative specials and say all positive values are also allowed. We have never excluded this kind of use, though I don't think we use it in the core. It doesn't say anything about extensions not in core, though. Perhaps it is worth emphasizing that this is not about making guarantees (although they would be much appreciated). This is about being able to make an educated guess what the most appropriate API would be. Currently, when my bindings encounter an enum, they basically tell the user uhh, it's an integer..., which, in the context of richly typed languages, is extremely awkward. It would be much better if I could tell the user Well, here's this bitfield object, and here are some flags for you to play with. Oh and by the way, really it's just a packaged integer. This would expose the full richness of the underlying C API (without breaking in the way you suggested), but does a much better job at providing something more sane (in the context of richly typed languages). Enumerations could be incomplete. For instance in the current xdg-shell.xml proposal in Weston, xdg_surface.state definition says that others are welcome to use other values from their own ranges. ... and as per the above, this would be fully allowed, since the internal integer representation is still available. Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. It also does not raise errors if you mismanage your memory (uninitialized memory, memory leaks, buffer overflow...), or if you forget to deal with a certain input combination, or if you declare but not define a function, ... With all due respect, this is not a good reason to block other languages from attempting to provide such information. If bindings erroneously not compile (ie. they error our while they shouldn't), then that's their problem, not yours. But this will typically hint at some underlying misunderstanding. In fact, in many occassions it was due to the Haskell typing system that I investigated internals of wayland, which taught me about all kinds subtleties I'm glad I didn't miss. The enum debate fits squarely in this kind of situation. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. Again, consider this the responsibility of bindings writers. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? In my case, I would really just expose a nicely packaged integer value (ie. the wire value), along with an API to e.g. match flags, or match enums. In other words, this would be perfectly allowed. But the, say, bitfield API would make much, much more sense from the user's point of view: bitwise computations are not just uncommon in Haskell, they're virtually nonexistent. And as long as the user wants to follow the hint and interpret the value as a bitfield, say, the user can do that. And if the user knows that something new was introduced in the protocol, then this information is available as well. I hope this answers your questions. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Sun, 19 Apr 2015 12:51:50 + Jeroen Bollen jbin...@gmail.com wrote: Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. Hi, I'm starting to think that using the name enum may have been a minor mistake. We are using it to define namespaced constants in the XML files, similar to how you use #define in C with some naming conventions. True, we use the enum type defitions to define these constants in C rather than #defines. I'm not sure if that has any more rationale behind it than it was convenient and allows debuggers to explain the values when cast to the enum type. Nothing guarantees, that an enum element strictly describes a complete enumeration or even a bitfield. You can have entries which contain several bits of a bitfield. You don't have to list all allowed entries, and so on. You could even have an enum that lists only special values and then say a set of other values are allowed, e.g. list some negative specials and say all positive values are also allowed. We have never excluded this kind of use, though I don't think we use it in the core. It doesn't say anything about extensions not in core, though. Enumerations could be incomplete. For instance in the current xdg-shell.xml proposal in Weston, xdg_surface.state definition says that others are welcome to use other values from their own ranges. Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. This and all the above are the likely reasons why adding the strict type information is not interesting, at least for me. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? So, the big question here is: do we even want to have strict enum types? Just because some languages have them is not a reason enough to bring them into the XML language, IMO. Answering that question would take effort while it is easy to just ignore it seemingly without any harm. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, 20 Apr 2015 09:43:42 +0200 Auke Booij a...@tulcod.com wrote: On 20 April 2015 at 09:03, Pekka Paalanen ppaala...@gmail.com wrote: Hi, Thanks for taking the time to respond. I'll address your issues one by one, but the overarching picture is that such typing information should and would not be interpreted by bindings as a promise, but rather as a hint. I'm starting to think that using the name enum may have been a minor mistake. We are using it to define namespaced constants in the XML files, similar to how you use #define in C with some naming conventions. True, we use the enum type defitions to define these constants in C rather than #defines. I'm not sure if that has any more rationale behind it than it was convenient and allows debuggers to explain the values when cast to the enum type. Nothing guarantees, that an enum element strictly describes a complete enumeration or even a bitfield. You can have entries which contain several bits of a bitfield. You don't have to list all allowed entries, and so on. You could even have an enum that lists only special values and then say a set of other values are allowed, e.g. list some negative specials and say all positive values are also allowed. We have never excluded this kind of use, though I don't think we use it in the core. It doesn't say anything about extensions not in core, though. Perhaps it is worth emphasizing that this is not about making guarantees (although they would be much appreciated). This is about being able to make an educated guess what the most appropriate API would be. Currently, when my bindings encounter an enum, they basically tell the user uhh, it's an integer..., which, in the context of richly typed languages, is extremely awkward. It would be much better if I could tell the user Well, here's this bitfield object, and here are some flags for you to play with. Oh and by the way, really it's just a packaged integer. This would expose the full richness of the underlying C API (without breaking in the way you suggested), but does a much better job at providing something more sane (in the context of richly typed languages). Then I am quite confused on how you would even use these specifications. That means I couldn't meaningfully review any such patches to the XML language, even if I had the time. Enumerations could be incomplete. For instance in the current xdg-shell.xml proposal in Weston, xdg_surface.state definition says that others are welcome to use other values from their own ranges. ... and as per the above, this would be fully allowed, since the internal integer representation is still available. Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. It also does not raise errors if you mismanage your memory (uninitialized memory, memory leaks, buffer overflow...), or if you forget to deal with a certain input combination, or if you declare but not define a function, ... With all due respect, this is not a good reason to block other languages from attempting to provide such information. If bindings erroneously not compile (ie. they error our while they shouldn't), then that's their problem, not yours. But this will typically hint at some underlying misunderstanding. In fact, in many occassions it was due to the Haskell typing system that I investigated internals of wayland, which taught me about all kinds subtleties I'm glad I didn't miss. The enum debate fits squarely in this kind of situation. This is only a reason why I believe people related to upstream are not really interested in solving or reviewing this. They have more important things to do. I know I am like that. I'm not here arguing that what you propose is bad or unacceptable. My only claim is that there is little interest to this among core developers to invest time in it. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. Again, consider this the responsibility of bindings writers. We still need to specify what all means, and enforce that specification also for C. When we do that, we might break things that used to work. If we don't do that, it will be useless because all developers writing only C could unitentionally break it for you by not following the spec and would never notice. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? In my case, I would really just expose a nicely packaged integer value (ie. the
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, 20 Apr 2015 at 09:03 Pekka Paalanen ppaala...@gmail.com wrote: Also, adding the strict type information to the XML spec has no benefit for C, which is the de facto language for Wayland core developers. A C compiler also does not raise errors if you violate the rules. This and all the above are the likely reasons why adding the strict type information is not interesting, at least for me. Making the enum rules more strict has a possibility to break existing users, but to me it is unclear if the benefit would outweigh that con or the freedom. On the wire, an enum or bitfield is still just an uint (or int), and a buggy client or server may cause the other to receive illegal values. Do the strongly typed languages have checks against that? Can you define what happens if the value is illegal for an enum? Or do you have to write that check manually in any case? So, the big question here is: do we even want to have strict enum types? It does indeed not provide any benefit for C, but if C is the only language to be targeted, there is not much use in there being an XML specification at all. It could've just been written out in C. I do agree that any changes should be compatible with C. I know in Rust, conversion from the `uint` to the `enum` type would have to be done manually, and error checking happens here. It does stop the user from passing illegal values to other servers however. It also makes it more clear what `enum`s are to be used with which arguments, and enforces this. I don't really see why adding that to the specification is an issue. If some `enum` types aren't complete, as in, they aren't the only valid values, then I see little value in having the `enum` in the specification in the first place. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
[PATCH wayland] Add enum attribute to arg elements
Hello, It seems like this discussion died off. Currently there is no way to tell, from the Wayland XML specification whether an argument is a bitfield, or whether the argument takes an enum and what enum this is. I am currently in the progress of writing a Wayland binding generator for the Rust language. This language, like many others is strongly typed. To make full usage of this type system, it would be beneficial to know from the specification whether an argument is a bitfield, and what enum type it takes. Surely there are more people who generate bindings to these strongly typed languages. How have you fixed the issue? Are there patched versions available, and maybe pending to be merged? I have looked around a bit, and didn't find anything, but then again, I'm not familiar with Wayland development. (This is the first time I use a mailing list!) Much appreciated, Jeroen Bollen ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. I do not believe we can change the XML format so that some enum elements would become bitfield instead. Existing generators would probably ignore bitfield and we need to keep the XML format stable. Considering all that, I'm not really sure that supporting strictly typed languages is worth the effort. After all, this API is for toolkit developers, and app developers will be using toolkit APIs, not this. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
2014-09-03 10:15 GMT+03:00 Pekka Paalanen ppaala...@gmail.com: On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. It is, in the sense that it doesn't automatically cast int to enums, so that could break the API. Also, wouldn't it possibily be an ABI break? Afaik enums don't have a very defined size, so what is now a int32 could become e.g. a 16 bits enum field. -- Giulio I do not believe we can change the XML format so that some enum elements would become bitfield instead. Existing generators would probably ignore bitfield and we need to keep the XML format stable. Considering all that, I'm not really sure that supporting strictly typed languages is worth the effort. After all, this API is for toolkit developers, and app developers will be using toolkit APIs, not this. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Wed, 3 Sep 2014 10:28:30 +0300 Giulio Camuffo giuliocamu...@gmail.com wrote: 2014-09-03 10:15 GMT+03:00 Pekka Paalanen ppaala...@gmail.com: On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. It is, in the sense that it doesn't automatically cast int to enums, so that could break the API. Also, wouldn't it possibily be an ABI break? Afaik enums don't have a very defined size, so what is now a int32 could become e.g. a 16 bits enum field. Yeah, I think that is another valid concern. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
Another possibility would of course be to add an 'is_bitfield=true' attribute to enum elements that are actually bit fields instead of using 'bitfield' elements. Every sanely written scanner should be able to cope with that, shouldn't it? On Wed, Sep 3, 2014 at 1:09 PM, Nils Chr. Brause nilschrbra...@gmail.com wrote: I see. In that case, I'll have to maintain my own xml file for my C++ bindings. Thanks, Nils On Wed, Sep 3, 2014 at 10:20 AM, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 3 Sep 2014 10:28:30 +0300 Giulio Camuffo giuliocamu...@gmail.com wrote: 2014-09-03 10:15 GMT+03:00 Pekka Paalanen ppaala...@gmail.com: On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. It is, in the sense that it doesn't automatically cast int to enums, so that could break the API. Also, wouldn't it possibily be an ABI break? Afaik enums don't have a very defined size, so what is now a int32 could become e.g. a 16 bits enum field. Yeah, I think that is another valid concern. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Wed, 3 Sep 2014 15:03:55 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: Another possibility would of course be to add an 'is_bitfield=true' attribute to enum elements that are actually bit fields instead of using 'bitfield' elements. Every sanely written scanner should be able to cope with that, shouldn't it? I believe so, yes. Btw. the enum size issue could bite you years from now, if you use enum in a public library API. If the enum happens to be 16-bit now, then someone adds a value that does not fit in 16 bits and the enum grows implicitly to 32 bits, that will break your library ABI in a very surprising way. That someone may not even know about your library, as he might be editing just some XML file in another project. If you can force enums to be always (at least these particular enums) 32 bits, you should be safe even when using them in public API. I'm still not sure how good idea that is, though. Thanks, pq On Wed, Sep 3, 2014 at 1:09 PM, Nils Chr. Brause nilschrbra...@gmail.com wrote: I see. In that case, I'll have to maintain my own xml file for my C++ bindings. Thanks, Nils On Wed, Sep 3, 2014 at 10:20 AM, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 3 Sep 2014 10:28:30 +0300 Giulio Camuffo giuliocamu...@gmail.com wrote: 2014-09-03 10:15 GMT+03:00 Pekka Paalanen ppaala...@gmail.com: On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. It is, in the sense that it doesn't automatically cast int to enums, so that could break the API. Also, wouldn't it possibily be an ABI break? Afaik enums don't have a very defined size, so what is now a int32 could become e.g. a 16 bits enum field. Yeah, I think that is another valid concern. Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Wed, Sep 3, 2014 at 9:15 AM, Pekka Paalanen ppaala...@gmail.com wrote: On Mon, 1 Sep 2014 22:07:44 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? Perhaps, if it does not cause problems on C++. I'm not sure, but I recall C++ being more strict than C wrt. enums. I do not believe we can change the XML format so that some enum elements would become bitfield instead. Existing generators would probably ignore bitfield and we need to keep the XML format stable. Considering all that, I'm not really sure that supporting strictly typed languages is worth the effort. After all, this API is for toolkit developers, and app developers will be using toolkit APIs, not this. Well, there are still plenty of people using low-level libx11/xcb instead of higher-level toolkits. Even on non-C languages. If they move to Wayland, they probably won't suddenly change their mind. ;) On Wed, Sep 3, 2014 at 3:44 PM, Pekka Paalanen ppaala...@gmail.com wrote: On Wed, 3 Sep 2014 15:03:55 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: Another possibility would of course be to add an 'is_bitfield=true' attribute to enum elements that are actually bit fields instead of using 'bitfield' elements. Every sanely written scanner should be able to cope with that, shouldn't it? I believe so, yes. Btw. the enum size issue could bite you years from now, if you use enum in a public library API. If the enum happens to be 16-bit now, then someone adds a value that does not fit in 16 bits and the enum grows implicitly to 32 bits, that will break your library ABI in a very surprising way. That someone may not even know about your library, as he might be editing just some XML file in another project. If you can force enums to be always (at least these particular enums) 32 bits, you should be safe even when using them in public API. I'm still not sure how good idea that is, though. Yes, using scoped enums, you can the the size. :) A new patch will follow in a few minutes. Thanks, Nils ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland] Add enum attribute to arg elements
On Mon, Sep 1, 2014 at 10:45 AM, Pekka Paalanen ppaala...@gmail.com wrote: On Sat, 30 Aug 2014 17:20:45 +0200 Nils Chr. Brause nilschrbra...@gmail.com wrote: There are programming languages, that are more strongly typed than C. People creating Wayland bindings for these languages probably want to make use of this strong type system by declaring each enumeration a distict type. For code generation to work with these languages, there needs to be information about which enumerations may be passed/received in which request/event arguments. This is accomplished by adding enum attributes to the arg elements of requests and events. The values of these attributes have the format $interface.$enum, where $interface is the name of the interface, where the enumeration is declared and $enum is the name of the enumeration, which is used in this argument. This might also be of documentary value. A nice idea, but did you check that all the things you tagged actually are enumerations and not bitfields? Everything named flags is usually a bitfield, which means you can 'or' different enum values together to form new legal values that are not listed in the enum. This will be a problem for languages which are strict with enums, and may even differentiate vs. bitfields. My bad, I didn't consider bitfields. This would also require a separate bitfield element for enums that are actually bitfields. With some enums I'm not sure, whether they are enums: - wl_pointer_button_state and wl_keyboard_key_state could as well be one bit bitfields. - wl_output_transform looks like an enumeration at first glance, but the values 270, flipped_90, flipped_180 and flipped_270 can actually be reconstructed by ORing the other values. So I guess it's a bitfield? Another problem with this patch is that while it adds new syntax to the protocol XML, it does not add anything that would either explain nor validate/enforce it. (We do not actually use the DTD for anything anymore.) Yes, we do not have a document describing the XML format, and that is a problem. Would be nice to start one, if anyone can work with Publican. The very least, wayland-scanner should be reading the enum attribute and check that the referenced enum exists. I'm not sure if it can generate a nice doc snippet into the generated code, but if there is a way to include that, it would be useful. We need *something* in the Wayland repository actually using these new attributes, so that they do not bit-rot immediately. I will look into the scanner code then. That is probably the easiest possibility to prevent bit-rot, since I never did anything with Publican. While I'm at that, I would also like to make use of the enum names in the generated C code. As far as I can see, this would not break any existing code, would it? Also, that would require the enum definitions to be at the top of the header files (just below the struct forward declarations), because enums cannot be forward declared. Would that be acceptable? If you do this addition because of strictly types languages, you'll probably also need the concept of bitfield in addition to enum, and use it where appropriate. I'd also like to punt this to the 1.7 development cycle, it is a bit late for 1.6. Yes, of course. :) Thanks, pq ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
[PATCH wayland] Add enum attribute to arg elements
There are programming languages, that are more strongly typed than C. People creating Wayland bindings for these languages probably want to make use of this strong type system by declaring each enumeration a distict type. For code generation to work with these languages, there needs to be information about which enumerations may be passed/received in which request/event arguments. This is accomplished by adding enum attributes to the arg elements of requests and events. The values of these attributes have the format $interface.$enum, where $interface is the name of the interface, where the enumeration is declared and $enum is the name of the enumeration, which is used in this argument. This might also be of documentary value. Signed-off-by: Nils Chr. Brause nilschrbra...@googlemail.com --- protocol/wayland.dtd | 1 + protocol/wayland.xml | 32 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/protocol/wayland.dtd b/protocol/wayland.dtd index b8b1573..1d8b9c7 100644 --- a/protocol/wayland.dtd +++ b/protocol/wayland.dtd @@ -25,5 +25,6 @@ !ATTLIST arg summary CDATA #IMPLIED !ATTLIST arg interface CDATA #IMPLIED !ATTLIST arg allow-null CDATA #IMPLIED + !ATTLIST arg enum CDATA #IMPLIED !ELEMENT description (#PCDATA) !ATTLIST description summary CDATA #REQUIRED diff --git a/protocol/wayland.xml b/protocol/wayland.xml index bb457bc..a632d2d 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -229,7 +229,7 @@ arg name=width type=int/ arg name=height type=int/ arg name=stride type=int/ - arg name=format type=uint/ + arg name=format type=uint enum=wl_shm.format/ /request request name=destroy type=destructor @@ -367,7 +367,7 @@ can be used for buffers. Known formats include argb and xrgb. /description - arg name=format type=uint/ + arg name=format type=uint enum=wl_shm.format/ /event /interface @@ -751,7 +751,7 @@ /description arg name=seat type=object interface=wl_seat summary=the wl_seat whose pointer is used/ arg name=serial type=uint summary=serial of the implicit grab on the pointer/ - arg name=edges type=uint summary=which edge or corner is being dragged/ + arg name=edges type=uint summary=which edge or corner is being dragged enum=wl_shell_surface.resize/ /request request name=set_toplevel @@ -784,7 +784,7 @@ arg name=parent type=object interface=wl_surface/ arg name=x type=int/ arg name=y type=int/ - arg name=flags type=uint/ + arg name=flags type=uint enum=wl_shell_surface.transient/ /request enum name=fullscreen_method @@ -835,7 +835,7 @@ with the dimensions for the output on which the surface will be made fullscreen. /description - arg name=method type=uint/ + arg name=method type=uint enum=wl_shell_surface.fullscreen_method/ arg name=framerate type=uint/ arg name=output type=object interface=wl_output allow-null=true/ /request @@ -868,7 +868,7 @@ arg name=parent type=object interface=wl_surface/ arg name=x type=int/ arg name=y type=int/ - arg name=flags type=uint/ + arg name=flags type=uint enum=wl_shell_surface.transient/ /request request name=set_maximized @@ -949,7 +949,7 @@ in surface local coordinates. /description - arg name=edges type=uint/ + arg name=edges type=uint enum=wl_shell_surface.resize/ arg name=width type=int/ arg name=height type=int/ /event @@ -1242,7 +1242,7 @@ wl_output.transform enum the invalid_transform protocol error is raised. /description - arg name=transform type=int/ + arg name=transform type=int enum=wl_output.transform/ /request !-- Version 3 additions -- @@ -1301,7 +1301,7 @@ keyboard or touch capabilities. The argument is a capability enum containing the complete set of capabilities this seat has. /description - arg name=capabilities type=uint/ + arg name=capabilities type=uint enum=wl_seat.capability/ /event request name=get_pointer @@ -1461,7 +1461,7 @@ arg name=serial type=uint/ arg name=time type=uint summary=timestamp with millisecond granularity/ arg name=button type=uint/ - arg name=state type=uint/ + arg name=state type=uint enum=wl_pointer.button_state/ /event enum name=axis @@ -1493,7 +1493,7 @@ /description arg name=time type=uint summary=timestamp with millisecond granularity/ - arg name=axis type=uint/ + arg name=axis type=uint enum=wl_pointer.axis/ arg name=value type=fixed/ /event @@ -1527,7 +1527,7 @@ This event provides a file descriptor to the client which can be memory-mapped to provide a keyboard mapping description. /description - arg name=format
