From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47619) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YbS2W-0002Ld-Jl for qemu-devel@nongnu.org; Fri, 27 Mar 2015 07:03:01 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YbS2Q-00012C-Tt for qemu-devel@nongnu.org; Fri, 27 Mar 2015 07:03:00 -0400 Received: from mx1.redhat.com ([209.132.183.28]:33078) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YbS2Q-000120-Lh for qemu-devel@nongnu.org; Fri, 27 Mar 2015 07:02:54 -0400 Received: from int-mx13.intmail.prod.int.phx2.redhat.com (int-mx13.intmail.prod.int.phx2.redhat.com [10.5.11.26]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id t2RB2rEs026150 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL) for ; Fri, 27 Mar 2015 07:02:53 -0400 From: Markus Armbruster References: <1427328837-4406-1-git-send-email-eblake@redhat.com> <1427328837-4406-3-git-send-email-eblake@redhat.com> Date: Fri, 27 Mar 2015 12:02:51 +0100 In-Reply-To: <1427328837-4406-3-git-send-email-eblake@redhat.com> (Eric Blake's message of "Wed, 25 Mar 2015 18:13:54 -0600") Message-ID: <87iodmn1no.fsf@blackfin.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain Subject: Re: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: qemu-devel@nongnu.org Eric Blake writes: > QObject is an internal coding concept and requires the reader to > reverse engineer the mapping; it is nicer to be explicit and call > out specific JSON types. > > Signed-off-by: Eric Blake > --- > docs/qapi-code-gen.txt | 24 ++++++++++++++---------- > 1 file changed, 14 insertions(+), 10 deletions(-) > > diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt > index 1f7d0ca..7fb0db7 100644 > --- a/docs/qapi-code-gen.txt > +++ b/docs/qapi-code-gen.txt > @@ -331,17 +331,21 @@ Resulting in this JSON object: > > Usage: { 'alternate: 'str', 'data': 'dict' } > > -An alternate type is one that allows a choice between two or more > -QObject data types (string, integer, number, or dictionary, but not > -array) on the wire. The definition is similar to a simple union type, > -where each branch of the dictionary names a type, and where an > -implicit C enum NameKind is created for the alternate Name. But > +An alternate type is one that allows a choice between two or more JSON > +data types on the wire. The definition is similar to a simple union > +type, where each branch of the dictionary names a QAPI type, and where > +an implicit C enum NameKind is created for the alternate Name. But > unlike a union, the discriminator string is never passed on the wire > -for QMP, instead appearing only in the generated C code. The type on > -the wire serves an implicit discriminator, which in turn means that an > -alternate can express a choice between a string and a single complex > -type (passed as a dictionary), but cannot distinguish between two > -different complex types. For example: > +for QMP, instead appearing only in the generated C code. Rather, the > +first byte of the value on the wire serves an implicit discriminator: I think "first byte of" is implementation detail, and should be left out. > +if the branch is typed as the 'bool' built-in, it 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 types it accepts a JSON string, and if it is typed as a named > +struct or union type it accepts a JSON object. Thus, an alternate can > +express a choice between a string and a single complex type (passed as > +a dictionary), but cannot distinguish between two different complex > +types or two different numeric built-in types. For example: > > { 'alternate': 'BlockRef', > 'data': { 'definition': 'BlockdevOptions',