On 10/22/2014 05:40 AM, Markus Armbruster wrote:
>> I think the question here really comes from RunState being an enum defined
>> in qapi-schema.json; so we could use that directly in the migration stream
>> if we were guaranteed that the encoding of that enum wasn't going to change.
>> Does qapi make any guarantees about the enum encoding?
>
> qapi-code-gen.txt in master is silent on the matter:
>
> === Enumeration types ===
>
> An enumeration type is a dictionary containing a single key whose value
> is a
> list of strings. An example enumeration is:
>
> { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
>
> Eric's "drop qapi nested structs" series improves the spec a lot.And I still need to find time to supply the next revision of that series... > The enumeration values are passed as strings over the QMP protocol, > but are encoded as C enum integral values in generated code. While > the C code starts numbering at 0, it is better to use explicit > comparisons to enum values than implicit comparisons to 0; the C code > will also include a generated enum member ending in _MAX for tracking > the size of the enum, useful when using common functions for > converting between strings and enum values. Since the wire format > always passes by name, it is acceptable to reorder or add new > enumeration members in any location without breaking QMP clients; > however, removing enum values would break compatibility. For any > complex type that has a field that will only contain a finite set of > string values, using an enum type for that field is better than > open-coding the field to be type 'str'. > > I figure relying on the QAPI code generator assigning values 0, 1, 2 in > order is fair. If you want to guarantee that more explicitly in the > spec, patch welcome (on top of Eric's, please). Yes, the generator guarantees that the order that enums are listed in a .json file will be the 0, 1, 2, ... values assigned in the C code. I'll add that in my revision. You cannot rely on the C values being stable unless the .json file takes care to not reorder names for the enum members; if we have enums where the C code is going to rely on a particular ordering, we probably ought to document that in the .json file (since MOST enums are designed for the C code to use them solely by symbolic name and not by specific value). > > A test or build-time assertion checking the values don't change would be > prudent. A comment next to the enum definition warning against > incompatible changes wouldn't hurt. Indeed, if you are going to rely on something that the generator happens to give but does not guarantee, then additional build-time checking and documentation is called for. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
