Re: qapi-schema esotera

[Eric Blake <eblake@redhat.com>]

On 8/3/20 11:49 AM, John Snow wrote:
> UNION is split into two primary forms:
> 
> 1. Simple (No discriminator nor base)
> 2. Flat (Discriminator and base)
> 
> In expr.py, I notice that we modify the perceived type of the 'type' 
> expression based on the two union forms.
> 
> 1a. Simple unions allow Array[T]
> 1b. Flat unions disallow Array[T]

Rather, branches in a simple unions are syntactic sugar for a wrapper 
struct that contains a single member 'data'; because of that extra 
nesting, the type of that single member is unconstrained.  In flat 
unionw, the type MUST be a QAPI struct, because its members will be used 
inline; as currently coded, this prevents the use of an intrinsic type 
('int', 'str') or an array type.

If you need to use an array type in a flat union, you can't do:

{ 'union' ...
   'data': { 'foo': [ 'MyBranch' ] } }

but you can provide a wrapper type yourself:

{ 'struct': 'MyBranch', 'data': { 'array': [ 'MyType' ] } }
{ 'union' ...
   'data': { 'foo': 'MyBranch' } }

> 
>  From the docs:
> 
> Syntax:
>      UNION = { 'union': STRING,
>                'data': BRANCHES,
>                '*if': COND,
>                '*features': FEATURES }
>            | { 'union': STRING,
>                'data': BRANCHES,
>                'base': ( MEMBERS | STRING ),
>                'discriminator': STRING,
>                '*if': COND,
>                '*features': FEATURES }
>      BRANCHES = { BRANCH, ... }
>      BRANCH = STRING : TYPE-REF
>             | STRING : { 'type': TYPE-REF, '*if': COND }
> 
> Both arms use the same "BRANCHES" grammar production, which both use 
> TYPE-REF.
> 
>      TYPE-REF = STRING | ARRAY-TYPE
>      ARRAY-TYPE = [ STRING ]
> 
> Implying that List[T] should be allowed for both productions.
> Can I ask for a ruling from the judges?

As you found, the docs are a bit misleading; the semantic constraint on 
flat union branches being a struct (because they will be inlined) 
prevents the use of type-refs that are valid in simple unions (where 
those simple types will be wrapped in an implicit struct).  A patch to 
improve the docs would be a reasonable idea.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org