From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:33525) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XW6rr-00021d-0Z for qemu-devel@nongnu.org; Mon, 22 Sep 2014 12:53:44 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XW6rm-0005z5-1r for qemu-devel@nongnu.org; Mon, 22 Sep 2014 12:53:38 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37977) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XW6rl-0005yg-QF for qemu-devel@nongnu.org; Mon, 22 Sep 2014 12:53:33 -0400 Message-ID: <54205405.3020700@redhat.com> Date: Mon, 22 Sep 2014 10:53:25 -0600 From: Eric Blake MIME-Version: 1.0 References: <1411165504-18198-1-git-send-email-eblake@redhat.com> <1411165504-18198-5-git-send-email-eblake@redhat.com> <87zjdrhlw3.fsf@blackfin.pond.sub.org> In-Reply-To: <87zjdrhlw3.fsf@blackfin.pond.sub.org> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="9lufTd0pidfsGRHoqwvuxuGmkA4D587tp" Subject: Re: [Qemu-devel] [PATCH v4 04/19] qapi: Document type-safety considerations List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: Fam Zheng , qemu-devel@nongnu.org, wenchaoqemu@gmail.com, Luiz Capitulino This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --9lufTd0pidfsGRHoqwvuxuGmkA4D587tp Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 09/22/2014 06:37 AM, Markus Armbruster wrote: > Eric Blake writes: >=20 >> =3D=3D=3D Union types =3D=3D=3D >> >> +Usage: { 'union': 'str', 'data': 'dict', '*base': 'complex-type-name'= , >> + '*discriminator': 'enum-type-name' } >> +or: { 'union': 'str', 'data': 'dict', 'discriminator': {} } >> + >=20 > Suggest to split usage into simple union, flat union and anonymous > union, like this: >=20 > Usage: { 'union': 'str', 'data': 'dict', '*base': 'complex-type-name' }= ^ simple > or: { 'union': 'str', 'data': 'dict', 'base': 'complex-type-name', > '*discriminator': 'enum-type-name' } ^ flat > or: { 'union': 'str', 'data': 'dict', 'discriminator': {} } ^ anonymous Except that someday, I'd like to have: { 'union': str', 'data': 'dict', 'discriminator': 'enum-type-name' } which, when compared with the simple and flat versions, means that base and discriminator are equally optional. But you are right that we don't have that form yet, and that the code currently requires that if base is specified, then discriminator is non-optional. I'll have to tweak this. >> + >> +In rare cases, QAPI cannot express a type-safe representation of a >> +corresponding QMP command. In these cases, if the command expression= >> +includes the key 'gen' with value 'no', then the 'data' or 'returns' >=20 > The implementation actually ignores the value of 'gen', but specifying > it must be 'no' doesn't hurt. Actually, see patch 14/19 later in the series, where I fix the code to enforce that it must be 'no' :) >=20 >> +member that intends to bypass generated type-safety and do its own >> +manual validation should use '**' rather than a valid type name. >> +Please try to avoid adding new commands that rely on this, and instea= d >> +use type-safe unions. For an example of bypass usage: >> + >> + { 'command': 'netdev_add', >> + 'data': {'type': 'str', 'id': 'str', '*props': '**'}, >> + 'gen': 'no' } >> + >> +Normally, the QAPI schema is used to describe synchronous exchanges, >> +where a response is expected. But in some cases, the action of a >> +command is expected to change state in a way that a successful >> +response is not possible (a failure message still returns a >> +dictionary). In this case, the command expression should include the= >> +optional key 'success-response' with value 'no'. >=20 > Learned something new here. To date, only qga uses this form. >> + >> +Events are defined with the keyword 'event'. It is not allowed to >> +name an event 'MAX', since the generator also produces a C enumeratio= n >> +of all event names with a generated _MAX value at the end. >=20 > One of the several places where the generator can thoughtlessly produce= > clashing identifiers. You're documenting one of them, which is an > improvement of sorts. I also enhance things later in the series to enforce this documentation := ) >=20 > Major improvement, thank you very much! I've trimmed your other comments (such as suggested line breaks) because I agree with them, and will incorporate them into either v5 (if the series needs respinning) or a followup patch (if this is the only patch that needs improvement). --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --9lufTd0pidfsGRHoqwvuxuGmkA4D587tp Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg iQEcBAEBCAAGBQJUIFQFAAoJEKeha0olJ0NqATAH+QFg6HfHuDzp882rrPC8qI7q h0Hpc+itOmJHhdWNwJ05rwCN2grFULHX1S6IpGa8zO/5wGwC1vdyZZM1SlolgQZk IcgMf4RfHLRSwxkDM9xJRq+MP1ldX1BE5cFaYMX6woanCAU6VLFekFBdHUaG5slh TgvQzsjoNYdJ/eXugtyfnsAWRAGrubSECd4Q2qAv1DNINckThtCjj9rbVMiDzhqz sxws1GDPD5lq7ChP/xjstvSFKEmyrD8efjAGKB+tXT1VXIkCLS72TEAbmARTbO+L Tr25x8Bl4D40WubgxEFdvEKJCi6h8LJ3EGJPLRIis3loWWcQ8dC0NqCjf9TDI6k= =C/Vq -----END PGP SIGNATURE----- --9lufTd0pidfsGRHoqwvuxuGmkA4D587tp--