Re: [Qemu-devel] [PATCH v5 01/28] qapi: Document type-safety considerations

[Eric Blake]

On 03/31/2015 09:09 AM, Kevin Wolf wrote:
> Am 24.03.2015 um 21:03 hat Eric Blake geschrieben:
>> Go into more details about the various types of valid expressions
>> in a qapi schema, including tweaks to document fixes being done
>> later in the current patch series.  Also fix some stale and missing
>> documentation in the QMP specification.
>>
>> Signed-off-by: Eric Blake <address@hidden>

>> +A flat union definition specifies a complex type as its base, and
>> +avoids nesting on the wire.  In this case, the fields of the complex
>> +type are included as top-level fields of the union dictionary in the
>> +QMP wire format, and the 'discriminator' field must be the name of an
>> +enum-typed member of the base type. An example definition is:
> 
> Adding full context:
> 
>      { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
>      { 'union': 'BlockdevOptions',
>        'base': 'BlockdevCommonOptions',
>        'data': { 'raw': 'RawOptions',
>                  'qcow2': 'Qcow2Options' } }

Oh, yikes.  I even outlawed this type of "simple union with base class"
later in the series, since no one was using it, and since it gets in the
way of my desire to move towards "simple union with type-safe enum
branching".  I'll have to revisit that text and document an actual flat
union in v6.

> 
>     And it looks like this on the wire:
> 
>      { "type": "qcow2",
>        "readonly": false,
>        "data" : { "backing-file": "/some/place/my-image",
>                   "lazy-refcounts": true } }
> 
> This is not a flat union for me, but really a simple one with an added
> base.

Correct - it is a bad example.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature