[PATCH v2 1/5] qapi: Enable enum member introspection to show more than name

[Markus Armbruster]

Kevin Wolf <kwolf at redhat.com> writes:

> Am 09.10.2021 um 14:09 hat Markus Armbruster geschrieben:
>> The next commit will add feature flags to enum members.  There's a
>> problem, though: query-qmp-schema shows an enum type's members as an
>> array of member names (SchemaInfoEnum member @values).  If it showed
>> an array of objects with a name member, we could simply add more
>> members to these objects.  Since it's just strings, we can't.
>> 
>> I can see three ways to correct this design mistake:
>> 
>> 1. Do it the way we should have done it, plus compatibility goo.
>> 
>>    We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum.  Since
>>    changing @values would be a compatibility break, add a new member
>>    @members instead.
>> 
>>    @values is now redundant.  In my testing, output of
>>    qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB).
>> 
>>    We can deprecate @values now and drop it later.  This will break
>>    outmoded clients.  Well-behaved clients such as libvirt are
>>    expected to break cleanly.
>> 
>> 2. Like 1, but omit "boring" elements of @member, and empty @member.
>> 
>>    @values does not become redundant.  @members augments it.  Somewhat
>>    cumbersome, but output of query-qmp-schema grows only as we make
>>    enum members non-boring.
>> 
>>    There is nothing to deprecate here.
>> 
>> 3. Versioned query-qmp-schema.
>> 
>>    query-qmp-schema provides either @values or @members.  The QMP
>>    client can select which version it wants.  There is no redundant
>>    output.
>> 
>>    We can deprecate old versions and eventually drop them.  This will
>>    break outmoded clients.  Breaking cleanly is easier than for 1.
>> 
>>    While 1 and 2 operate within the common rules for compatible
>>    evolution apply (section "Compatibility considerations" in
>>    docs/devel/qapi-code-gen.rst), 3 bypasses them.  Attractive when
>>    operating within the rules is just too awkward.  Not the case here.
>> 
>> This commit implements 1.  Libvirt developers prefer it.
>> 
>> Signed-off-by: Markus Armbruster <armbru at redhat.com>
>> ---
>>  qapi/introspect.json       | 21 +++++++++++++++++++--
>>  scripts/qapi/introspect.py | 18 ++++++++++++++----
>>  2 files changed, 33 insertions(+), 6 deletions(-)
>
> docs/devel/qapi-code-gen.rst still says:
>
>   The SchemaInfo for an enumeration type has meta-type "enum" and
>   variant member "values".  The values are listed in no particular
>   order; clients must search the entire enum when learning whether a
>   particular value is supported.
>
>   Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
>
>       { "name": "MyEnum", "meta-type": "enum",
>         "values": [ "value1", "value2", "value3" ] }
>
> It probably needs an update.

It sure does.  Thanks!