Re: [Qemu-block] [Qemu-devel] [PATCH v9 14/37] qapi: Swap visit_* arguments for consistent 'name' placement

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> JSON uses "name":value, but many of our visitor interfaces were
> called with visit_type_FOO(v, &value, name, errp).  This can be
> a bit confusing to have to mentally swap the parameter order to
> match JSON order.  It's particularly bad for visit_start_struct(),
> where the 'name' parameter is smack in the middle of the
> otherwise-related group of 'obj, kind, size' parameters! It's
> time to do a global swap of the parameter ordering, so that the
> 'name' parameter is always immediately after the Visitor argument.

Yes, please!

> Additional reasons in favor of the swap: name is always an input
> parameter, while &value is sometimes an output parameter (depending
> on whether the caller is using an input visitor); and it is nicer
> to list input parameters first.

Except when it isn't: memcpy(), strcat(), ...  I'd scratch this
argument.  The case for the transformation is plenty strong without it.


>                                  Also, the existing include/qjson.h
> prefers listing 'name' first in json_prop_*(), and I have plans to
> unify that file with the qapi visitors; listing 'name' first in
> qapi will minimize churn to the (admittedly few) qjson.h clients.
>
> The next patches will then fix docs, object.h, visitor-impl.h, and
> those clients to match.
>
> Done by first patching scripts/qapi*.py by hand to make generated
> files do what I want, then by running the following Coccinelle
> script to affect the rest of the code base:
>  $ spatch --sp-file script `git grep -l '\bvisit_' -- '**/*.[ch]'`
> I then had to apply some touchups (Coccinelle insisted on TAB
> indentation in visitor.h, and botched the signature of
> visit_type_enum() by rewriting 'const char *const strings[]' to
> the syntactically invalid 'const char*const[] strings').
>
>     // Part 1: Swap declaration order
>     @@
>     type TV, TErr, TObj, T1, T2;
>     identifier OBJ, ARG1, ARG2;
>     @@
>      void visit_start_struct
>     -(TV v, TObj OBJ, T1 ARG1, const char *name, T2 ARG2, TErr errp)
>     +(TV v, const char *name, TObj OBJ, T1 ARG1, T2 ARG2, TErr errp)

Rotates second to fourth parameters right.  Their types are sufficiently
incompatible, so the compiler should catch inconsistencies.

Similar argument for the other functions.

>      { ... }
>
>     @@
>     type bool, TV, T1;
>     identifier ARG1;
>     @@
>      bool visit_optional
>     -(TV v, T1 ARG1, const char *name)
>     +(TV v, const char *name, T1 ARG1)
>      { ... }
>
>     @@
>     type TV, TErr, TObj, T1;
>     identifier OBJ, ARG1;
>     @@
>      void visit_get_next_type
>     -(TV v, TObj OBJ, T1 ARG1, const char *name, TErr errp)
>     +(TV v, const char *name, TObj OBJ, T1 ARG1, TErr errp)
>      { ... }
>
>     @@
>     type TV, TErr, TObj, T1, T2;
>     identifier OBJ, ARG1, ARG2;
>     @@
>      void visit_type_enum
>     -(TV v, TObj OBJ, T1 ARG1, T2 ARG2, const char *name, TErr errp)
>     +(TV v, const char *name, TObj OBJ, T1 ARG1, T2 ARG2, TErr errp)
>      { ... }
>
>     @@
>     type TV, TErr, TObj;
>     identifier OBJ;
>     identifier VISIT_TYPE =~ "^visit_type_";
>     @@
>      void VISIT_TYPE
>     -(TV v, TObj OBJ, const char *name, TErr errp)
>     +(TV v, const char *name, TObj OBJ, TErr errp)
>      { ... }
>
>     // Part 2: swap caller order
>     @@
>     expression V, NAME, OBJ, ARG1, ARG2, ERR;
>     identifier VISIT_TYPE =~ "^visit_type_";
>     @@
>     (
>     -visit_start_struct(V, OBJ, ARG1, NAME, ARG2, ERR)
>     +visit_start_struct(V, NAME, OBJ, ARG1, ARG2, ERR)
>     |
>     -visit_optional(V, ARG1, NAME)
>     +visit_optional(V, NAME, ARG1)
>     |
>     -visit_get_next_type(V, OBJ, ARG1, NAME, ERR)
>     +visit_get_next_type(V, NAME, OBJ, ARG1, ERR)
>     |
>     -visit_type_enum(V, OBJ, ARG1, ARG2, NAME, ERR)
>     +visit_type_enum(V, NAME, OBJ, ARG1, ARG2, ERR)
>     |
>     -VISIT_TYPE(V, OBJ, NAME, ERR)
>     +VISIT_TYPE(V, NAME, OBJ, ERR)
>     )
>
> Signed-off-by: Eric Blake <address@hidden>
> Reviewed-by: Marc-André Lureau <address@hidden>

Didn't check the patch closely.