[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v6 15/36] qapi: Document new 'alternate' meta-type
From: |
Eric Blake |
Subject: |
[Qemu-devel] [PATCH v6 15/36] qapi: Document new 'alternate' meta-type |
Date: |
Sat, 4 Apr 2015 22:07:46 -0600 |
The next patch will quit special-casing "'union':'Foo',
'discriminator':{}" and instead use "'alternate':'Foo'".
Separating docs from implementation makes it easier to focus
on wording without holding up code. In particular, making
alternate a separate type makes for a nice type hierarchy:
/-------- meta-type ------\
/ | \
simple types alternate complex types
| | | |
built-in enum type(struct) union
| \ / / \
numeric string simple flat
A later patch will then clean up 'type' vs. 'struct'
confusion.
Signed-off-by: Eric Blake <address@hidden>
---
v6: split from v5:12/28, merge in 2/5 of doc followup series, as
well as Markus' wording improvements
---
docs/qapi-code-gen.txt | 57 +++++++++++++++++++++++++++++++-------------------
1 file changed, 36 insertions(+), 21 deletions(-)
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 585cb24..8a76cc1 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -84,11 +84,12 @@ the definition of complex structs that can have mutually
recursive
types, and allows for indefinite nesting of QMP that satisfies the
schema. A type name should not be defined more than once.
-There are six top-level expressions recognized by the parser:
-'include', 'command', 'type', 'enum', 'union', and 'event'. There are
-several built-in types, such as 'int' and 'str'; additionally, the
-top-level expressions can define complex types, enumeration types, and
-several flavors of union types. The 'command' and 'event' expressions
+There are seven top-level expressions recognized by the parser:
+'include', 'command', 'type', 'enum', 'union', 'alternate', and
+'event'. There are several groups of types: simple types (a number of
+built-in types, such as 'int' and 'str'; as well as enumerations),
+complex types (structs and two flavors of unions), and alternate types
+(a choice between other types). The 'command' and 'event' expressions
can refer to existing types by name, or list an anonymous type as a
dictionary. Listing a type name inside an array refers to a
single-dimension array of that type; multi-dimension arrays are not
@@ -260,14 +261,12 @@ open-coding the field to be type 'str'.
Usage: { 'union': STRING, 'data': DICT }
or: { 'union': STRING, 'data': DICT, 'base': COMPLEX-TYPE-NAME,
'discriminator': ENUM-MEMBER-OF-BASE }
-or: { 'union': STRING, 'data': DICT, 'discriminator': {} }
Union types are used to let the user choose between several different
-variants for an object. There are three flavors: simple (no
-discriminator or base), flat (both base and discriminator are
-strings), and anonymous (discriminator is an empty dictionary). A
-union type is defined using a data dictionary as explained in the
-following paragraphs.
+variants for an object. There are two flavors: simple (no
+discriminator or base), flat (both discriminator and base). A union
+type is defined using a data dictionary as explained in the following
+paragraphs.
A simple union type defines a mapping from automatic discriminator
values to data types like in this example:
@@ -349,20 +348,36 @@ is identical on the wire to:
'data': { 'one': 'Branch1', 'two': 'Branch2' } }
-The final flavor of unions is an anonymous union. While the other two
-union types are always passed as a JSON object in the wire format, an
-anonymous union instead allows the direct use of different types in
-its place. Anonymous unions are declared using an empty dictionary as
-their discriminator. The discriminator values never appear on the
-wire, they are only used in the generated C code. Anonymous unions
-cannot have a base type.
+=== Alternate types ===
- { 'union': 'BlockRef',
- 'discriminator': {},
+Usage: { 'alternate': STRING, 'data': DICT }
+
+An alternate type is one that allows a choice between two or more JSON
+data types (string, integer, number, or object, but currently not
+array) on the wire. The definition is similar to a simple union type,
+where each branch of the union names a QAPI type. For example:
+
+ { 'alternate': 'BlockRef',
'data': { 'definition': 'BlockdevOptions',
'reference': 'str' } }
-This example allows using both of the following example objects:
+Just like for a simple union, an implicit C enum 'NameKind' is created
+to enumerate the branches for the alternate 'Name'.
+
+Unlike a union, the discriminator string is never passed on the wire
+for QMP. Instead, the value's JSON type serves as an implicit
+discriminator, which in turn means that an alternate can only express
+a choice between types represented differently in JSON. If a branch
+is typed as the 'bool' built-in, the alternate accepts true and false;
+if it is typed as any of the various numeric built-ins, it accepts a
+JSON number; if it is typed as a 'str' built-in or named enum type, it
+accepts a JSON string; and if it is typed as a complex type (struct or
+union), it accepts a JSON object. Two different complex types, for
+instance, aren't permitted, because both are represented as a JSON
+object.
+
+The example alternate declaration above allows using both of the
+following example objects:
{ "file": "my_existing_block_device_id" }
{ "file": { "driver": "file",
--
2.1.0
- Re: [Qemu-devel] [PATCH v6 07/36] qapi: Better error messages for bad enums, (continued)
- [Qemu-devel] [PATCH v6 09/36] qapi: Clean up test coverage of simple unions, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 06/36] qapi: Add some enum tests, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 10/36] qapi: Forbid base without discriminator in unions, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerations, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 15/36] qapi: Document new 'alternate' meta-type,
Eric Blake <=
- [Qemu-devel] [PATCH v6 13/36] qapi: Segregate anonymous unions into alternates in generator, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 14/36] qapi: Rename anonymous union type in test, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 11/36] qapi: Tighten checking of unions, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 21/36] qapi: Allow true, false and null in schema json, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 17/36] qapi: Add some expr tests, Eric Blake, 2015/04/05