| Message ID | 20210211183118.422036-2-kwolf@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | qapi: Add support for aliases | expand |
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;
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 @@ -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). + * + * 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;
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(+)