Re: [PATCH v2 1/6] qapi: Add interfaces for alias support to Visitor

[Markus Armbruster]

Kevin Wolf <kwolf@redhat.com> writes:

> This adds functions to the Visitor interface that can be used to define
> aliases and alias scopes.
>
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>  include/qapi/visitor-impl.h | 12 ++++++++++
>  include/qapi/visitor.h      | 44 +++++++++++++++++++++++++++++++++++++
>  qapi/qapi-visit-core.c      | 22 +++++++++++++++++++
>  3 files changed, 78 insertions(+)
>
> diff --git a/include/qapi/visitor-impl.h b/include/qapi/visitor-impl.h
> index 7362c043be..d9a6874528 100644
> --- a/include/qapi/visitor-impl.h
> +++ b/include/qapi/visitor-impl.h
> @@ -113,6 +113,18 @@ struct Visitor
>         The core takes care of the return type in the public interface. */
>      void (*optional)(Visitor *v, const char *name, bool *present);
>  
> +    /*
> +     * Optional; intended for input visitors. If not given, aliases are
> +     * ignored.
> +     */
> +    void (*define_alias)(Visitor *v, const char *name, const char **source);
> +
> +    /* Must be set if define_alias is set */
> +    void (*start_alias_scope)(Visitor *v);
> +
> +    /* Must be set if define_alias is set */
> +    void (*end_alias_scope)(Visitor *v);
> +
>      /* Must be set */
>      VisitorType type;
>  
> diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h
> index ebc19ede7f..2ecbc20624 100644
> --- a/include/qapi/visitor.h
> +++ b/include/qapi/visitor.h

Still missing: an update of the big comment.  That's okay, we can do
that last.

> @@ -459,6 +459,50 @@ void visit_end_alternate(Visitor *v, void **obj);
>   */
>  bool visit_optional(Visitor *v, const char *name, bool *present);
>  
> +/*
> + * Defines a new alias rule.
> + *
> + * If @name is non-NULL, the member called @name in the external
> + * representation of the currently visited object is defined as an
> + * alias for the member described by @source.  It is not allowed to
> + * call this function when the currently visited type is not an
> + * object.
> + *
> + * If @name is NULL, all members of the object described by @source
> + * are considered to have alias members with the same key in the
> + * currently visited object.
> + *
> + * @source is a NULL-terminated non-empty array of names that describe
> + * the path to a member, starting from the currently visited object.
> + * All elements in @source except the last one should describe
> + * objects.  If an intermediate element refers to a member with a
> + * non-object type, the alias won't work (this case can legitimately
> + * happen in unions where an alias only makes sense for one branch,
> + * but not for another).

A sufficiently paranoid reader will now realize that the system won't
catch mistakes.  I'm not objecting to that; I understand distinguishing
aliases that may work (just not now) from aliases that can't work is
non-trivial and quite probably not worth it.  I'm just wondering whether
we should be even more explicit, to help insufficiently paranoid
readers.

Here's a possible argument against: we expect this function to be used
only by generated code, and the maintainers of the generator are
expected to be sufficiently paranoid.

The same issue might exist in qapi-code-gen.txt.

> + *
> + * The alias stays valid until the current alias scope ends.
> + * visit_start/end_struct() implicitly start/end an alias scope.
> + * Additionally, visit_start/end_alias_scope() can be used to explicitly
> + * create a nested alias scope.
> + */
> +void visit_define_alias(Visitor *v, const char *name, const char **source);
> +
> +/*
> + * Begins an explicit alias scope.
> + *
> + * Alias definitions after here will only stay valid until the
> + * corresponding visit_end_alias_scope() is called.
> + */
> +void visit_start_alias_scope(Visitor *v);
> +
> +/*
> + * Ends an explicit alias scope.
> + *
> + * Alias definitions between the correspoding visit_start_alias_scope()
> + * call and here go out of scope and won't apply in later code any more.
> + */
> +void visit_end_alias_scope(Visitor *v);
> +
>  /*
>   * Visit an enum value.
>   *
> diff --git a/qapi/qapi-visit-core.c b/qapi/qapi-visit-core.c
> index 7e5f40e7f0..651dd88e02 100644
> --- a/qapi/qapi-visit-core.c
> +++ b/qapi/qapi-visit-core.c
> @@ -135,6 +135,28 @@ bool visit_optional(Visitor *v, const char *name, bool 
> *present)
>      return *present;
>  }
>  
> +void visit_define_alias(Visitor *v, const char *name, const char **source)
> +{
> +    assert(source[0] != NULL);
> +    if (v->define_alias) {
> +        v->define_alias(v, name, source);
> +    }
> +}
> +
> +void visit_start_alias_scope(Visitor *v)
> +{
> +    if (v->start_alias_scope) {
> +        v->start_alias_scope(v);
> +    }
> +}
> +
> +void visit_end_alias_scope(Visitor *v)
> +{
> +    if (v->end_alias_scope) {
> +        v->end_alias_scope(v);
> +    }
> +}
> +
>  bool visit_is_input(Visitor *v)
>  {
>      return v->type == VISITOR_INPUT;