From 64594e2bcc9a734bfabfaa8a75e08b4c9d920569 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 15 Apr 2020 10:30:44 +0200 Subject: qobject: Clean up QLIST_FOREACH_ENTRY() QLIST_FOREACH_ENTRY() traverses a tail queue manually. Use QTAILQ_FIRST() and QTAILQ_NEXT() instead. Signed-off-by: Markus Armbruster Message-Id: <20200415083048.14339-2-armbru@redhat.com> Reviewed-by: Eric Blake --- include/qapi/qmp/qlist.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/qapi/qmp/qlist.h b/include/qapi/qmp/qlist.h index 8d2c32c..07ecae8 100644 --- a/include/qapi/qmp/qlist.h +++ b/include/qapi/qmp/qlist.h @@ -34,10 +34,10 @@ void qlist_append_int(QList *qlist, int64_t value); void qlist_append_null(QList *qlist); void qlist_append_str(QList *qlist, const char *value); -#define QLIST_FOREACH_ENTRY(qlist, var) \ - for ((var) = ((qlist)->head.tqh_first); \ - (var); \ - (var) = ((var)->next.tqe_next)) +#define QLIST_FOREACH_ENTRY(qlist, var) \ + for ((var) = QTAILQ_FIRST(&(qlist)->head); \ + (var); \ + (var) = QTAILQ_NEXT((var), next)) static inline QObject *qlist_entry_obj(const QListEntry *entry) { -- cgit v1.1 From 2f2ec111795119b2e020bc0cbf4b5f42878574b2 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 15 Apr 2020 10:30:46 +0200 Subject: qobject: Eliminate qlist_iter(), use QLIST_FOREACH_ENTRY() instead qlist_iter() has just three uses outside tests/. Replace by QLIST_FOREACH_ENTRY() for more concise code and less type punning. Signed-off-by: Markus Armbruster Message-Id: <20200415083048.14339-4-armbru@redhat.com> Reviewed-by: Eric Blake --- include/qapi/qmp/qlist.h | 2 -- 1 file changed, 2 deletions(-) (limited to 'include') diff --git a/include/qapi/qmp/qlist.h b/include/qapi/qmp/qlist.h index 07ecae8..595b794 100644 --- a/include/qapi/qmp/qlist.h +++ b/include/qapi/qmp/qlist.h @@ -47,8 +47,6 @@ static inline QObject *qlist_entry_obj(const QListEntry *entry) QList *qlist_new(void); QList *qlist_copy(QList *src); void qlist_append_obj(QList *qlist, QObject *obj); -void qlist_iter(const QList *qlist, - void (*iter)(QObject *obj, void *opaque), void *opaque); QObject *qlist_pop(QList *qlist); QObject *qlist_peek(QList *qlist); int qlist_empty(const QList *qlist); -- cgit v1.1 From 7b1cd1c65abad70b26fbe9b11991bd88f0d956e1 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 15 Apr 2020 10:30:47 +0200 Subject: qobject: Eliminate qdict_iter(), use qdict_first(), qdict_next() qdict_iter() has just three uses and no test coverage. Replace by qdict_first(), qdict_next() for more concise code and less type punning. Signed-off-by: Markus Armbruster Message-Id: <20200415083048.14339-5-armbru@redhat.com> Reviewed-by: Eric Blake --- include/qapi/qmp/qdict.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'include') diff --git a/include/qapi/qmp/qdict.h b/include/qapi/qmp/qdict.h index 7f3ec10..da94234 100644 --- a/include/qapi/qmp/qdict.h +++ b/include/qapi/qmp/qdict.h @@ -40,9 +40,6 @@ void qdict_del(QDict *qdict, const char *key); int qdict_haskey(const QDict *qdict, const char *key); QObject *qdict_get(const QDict *qdict, const char *key); bool qdict_is_equal(const QObject *x, const QObject *y); -void qdict_iter(const QDict *qdict, - void (*iter)(const char *key, QObject *obj, void *opaque), - void *opaque); const QDictEntry *qdict_first(const QDict *qdict); const QDictEntry *qdict_next(const QDict *qdict, const QDictEntry *entry); void qdict_destroy_obj(QObject *obj); -- cgit v1.1 From 3777d36e674ca3b75b63413b4fb506b108309144 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:24 +0200 Subject: qapi: Belatedly update visitor.h's big comment for QAPI modules Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-2-armbru@redhat.com> --- include/qapi/visitor.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index c5b2385..f8a0fc1 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -58,7 +58,7 @@ * * where T is FOO for scalar types, and FOO * otherwise. The scalar * visitors are declared here; the remaining visitors are generated in - * qapi-visit.h. + * qapi-visit-MODULE.h. * * The @name parameter of visit_type_FOO() describes the relation * between this QAPI value and its parent container. When visiting @@ -86,16 +86,16 @@ * by manual construction. * * For the QAPI object types (structs, unions, and alternates), there - * is an additional generated function in qapi-visit.h compatible - * with: + * is an additional generated function in qapi-visit-MODULE.h + * compatible with: * * void visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp); * * for visiting the members of a type without also allocating the QAPI * struct. * - * Additionally, in qapi-types.h, all QAPI pointer types (structs, - * unions, alternates, and lists) have a generated function compatible + * Additionally, QAPI pointer types (structs, unions, alternates, and + * lists) have a generated function in qapi-types-MODULE.h compatible * with: * * void qapi_free_FOO(FOO *obj); -- cgit v1.1 From 294c90662ac9daae2c3bbf608296cf037925bd95 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:25 +0200 Subject: qapi: Fix the virtual walk example in visitor.h's big comment Call visit_check_list(). Missed in commit a4a1c70dc7 "qapi: Make input visitors detect unvisited list tails". Drop an irrelevant error_propagate() while there. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-3-armbru@redhat.com> --- include/qapi/visitor.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index f8a0fc1..7f63e4c 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -215,6 +215,9 @@ * goto outlist; * } * outlist: + * if (!err) { + * visit_check_list(v, &err); + * } * visit_end_list(v, NULL); * if (!err) { * visit_check_struct(v, &err); @@ -222,7 +225,6 @@ * outobj: * visit_end_struct(v, NULL); * out: - * error_propagate(errp, err); * visit_free(v); * */ -- cgit v1.1 From 782586c77103d297f38e78950dfbe2a31a3b2924 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:26 +0200 Subject: qapi: Fix typo in visit_start_list()'s contract Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-4-armbru@redhat.com> --- include/qapi/visitor.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index 7f63e4c..c5d0ce9 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -345,9 +345,9 @@ void visit_end_struct(Visitor *v, void **obj); * input visitors set *@list to NULL. * * After visit_start_list() succeeds, the caller may visit its members - * one after the other. A real visit (where @obj is non-NULL) uses + * one after the other. A real visit (where @list is non-NULL) uses * visit_next_list() for traversing the linked list, while a virtual - * visit (where @obj is NULL) uses other means. For each list + * visit (where @list is NULL) uses other means. For each list * element, call the appropriate visit_type_FOO() with name set to * NULL and obj set to the address of the value member of the list * element. Finally, visit_end_list() needs to be called with the -- cgit v1.1 From c5460d5e19b4c531e86f8be0e00ab463fae7548b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:27 +0200 Subject: qapi: Document @errp usage more thoroughly in visitor.h Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-5-armbru@redhat.com> --- include/qapi/visitor.h | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index c5d0ce9..09df709 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -284,9 +284,7 @@ void visit_free(Visitor *v); * into *@obj. @obj may also be NULL for a virtual walk, in which * case @size is ignored. * - * @errp obeys typical error usage, and reports failures such as a - * member @name is not present, or present but not an object. On - * error, input visitors set *@obj to NULL. + * On failure, set *@obj to NULL and store an error through @errp. * * After visit_start_struct() succeeds, the caller may visit its * members one after the other, passing the member's name and address @@ -303,8 +301,7 @@ void visit_start_struct(Visitor *v, const char *name, void **obj, /* * Prepare for completing an object visit. * - * @errp obeys typical error usage, and reports failures such as - * unparsed keys remaining in the input stream. + * On failure, store an error through @errp. * * Should be called prior to visit_end_struct() if all other * intermediate visit steps were successful, to allow the visitor one @@ -340,9 +337,7 @@ void visit_end_struct(Visitor *v, void **obj); * allow @list to be NULL for a virtual walk, in which case @size is * ignored. * - * @errp obeys typical error usage, and reports failures such as a - * member @name is not present, or present but not a list. On error, - * input visitors set *@list to NULL. + * On failure, set *@list to NULL and store an error through @errp. * * After visit_start_list() succeeds, the caller may visit its members * one after the other. A real visit (where @list is non-NULL) uses @@ -376,8 +371,7 @@ GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size); /* * Prepare for completing a list visit. * - * @errp obeys typical error usage, and reports failures such as - * unvisited list tail remaining in the input stream. + * On failure, store an error through @errp. * * Should be called prior to visit_end_list() if all other * intermediate visit steps were successful, to allow the visitor one @@ -409,8 +403,10 @@ void visit_end_list(Visitor *v, void **list); * * @obj must not be NULL. Input and clone visitors use @size to * determine how much memory to allocate into *@obj, then determine - * the qtype of the next thing to be visited, stored in (*@obj)->type. - * Other visitors will leave @obj unchanged. + * the qtype of the next thing to be visited, and store it in + * (*@obj)->type. Other visitors leave @obj unchanged. + * + * On failure, set *@obj to NULL and store an error through @errp. * * If successful, this must be paired with visit_end_alternate() with * the same @obj to clean up, even if visiting the contents of the @@ -463,8 +459,9 @@ bool visit_optional(Visitor *v, const char *name, bool *present); * * Currently, all input visitors parse text input, and all output * visitors produce text output. The mapping between enumeration - * values and strings is done by the visitor core, using @strings; it - * should be the ENUM_lookup array from visit-types.h. + * values and strings is done by the visitor core, using @lookup. + * + * On failure, store an error through @errp. * * May call visit_type_str() under the hood, and the enum visit may * fail even if the corresponding string visit succeeded; this implies @@ -488,6 +485,8 @@ bool visit_is_input(Visitor *v); * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. + * + * On failure, store an error through @errp. */ void visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp); @@ -564,6 +563,8 @@ void visit_type_size(Visitor *v, const char *name, uint64_t *obj, * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. + * + * On failure, store an error through @errp. */ void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); @@ -581,6 +582,8 @@ void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); * It is safe to cast away const when preparing a (const char *) value * into @obj for use by an output visitor. * + * On failure, set *@obj to NULL and store an error through @errp. + * * FIXME: Callers that try to output NULL *obj should not be allowed. */ void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp); @@ -594,6 +597,8 @@ void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp); * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. Visitors should * document if infinity or NaN are not permitted. + * + * On failure, store an error through @errp. */ void visit_type_number(Visitor *v, const char *name, double *obj, Error **errp); @@ -608,6 +613,8 @@ void visit_type_number(Visitor *v, const char *name, double *obj, * other visitors will leave *@obj unchanged. *@obj must be non-NULL * for output visitors. * + * On failure, set *@obj to NULL and store an error through @errp. + * * Note that some kinds of input can't express arbitrary QObject. * E.g. the visitor returned by qobject_input_visitor_new_keyval() * can't create numbers or booleans, only strings. @@ -622,6 +629,8 @@ void visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp); * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors ignore *@obj. + * + * On failure, set *@obj to NULL and store an error through @errp. */ void visit_type_null(Visitor *v, const char *name, QNull **obj, Error **errp); -- cgit v1.1 From 554d6586ae96216771fe701c9d3a321e2adb057b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:28 +0200 Subject: qapi: Polish prose in visitor.h Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-6-armbru@redhat.com> --- include/qapi/visitor.h | 104 +++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 50 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index 09df709..a425ea5 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -25,19 +25,21 @@ * for doing work at each node of a QAPI graph; it can also be used * for a virtual walk, where there is no actual QAPI C struct. * - * There are four kinds of visitor classes: input visitors (QObject, - * string, and QemuOpts) parse an external representation and build - * the corresponding QAPI graph, output visitors (QObject and string) take - * a completed QAPI graph and generate an external representation, the - * dealloc visitor can take a QAPI graph (possibly partially - * constructed) and recursively free its resources, and the clone - * visitor performs a deep clone of one QAPI object to another. While - * the dealloc and QObject input/output visitors are general, the string, - * QemuOpts, and clone visitors have some implementation limitations; - * see the documentation for each visitor for more details on what it - * supports. Also, see visitor-impl.h for the callback contracts - * implemented by each visitor, and docs/devel/qapi-code-gen.txt for more - * about the QAPI code generator. + * There are four kinds of visitors: input visitors (QObject, string, + * and QemuOpts) parse an external representation and build the + * corresponding QAPI object, output visitors (QObject and string) + * take a QAPI object and generate an external representation, the + * dealloc visitor takes a QAPI object (possibly partially + * constructed) and recursively frees it, and the clone visitor + * performs a deep clone of a QAPI object. + * + * While the dealloc and QObject input/output visitors are general, + * the string, QemuOpts, and clone visitors have some implementation + * limitations; see the documentation for each visitor for more + * details on what it supports. Also, see visitor-impl.h for the + * callback contracts implemented by each visitor, and + * docs/devel/qapi-code-gen.txt for more about the QAPI code + * generator. * * All of the visitors are created via: * @@ -45,11 +47,15 @@ * * A visitor should be used for exactly one top-level visit_type_FOO() * or virtual walk; if that is successful, the caller can optionally - * call visit_complete() (for now, useful only for output visits, but - * safe to call on all visits). Then, regardless of success or - * failure, the user should call visit_free() to clean up resources. - * It is okay to free the visitor without completing the visit, if - * some other error is detected in the meantime. + * call visit_complete() (useful only for output visits, but safe to + * call on all visits). Then, regardless of success or failure, the + * user should call visit_free() to clean up resources. It is okay to + * free the visitor without completing the visit, if some other error + * is detected in the meantime. + * + * The clone and dealloc visitor should not be used directly outside + * of QAPI code. Use the qapi_free_FOO() and QAPI_CLONE() instead, + * described below. * * All QAPI types have a corresponding function with a signature * roughly compatible with this: @@ -68,22 +74,26 @@ * alternate, @name should equal the name used for visiting the * alternate. * - * The visit_type_FOO() functions expect a non-null @obj argument; - * they allocate *@obj during input visits, leave it unchanged on - * output visits, and recursively free any resources during a dealloc - * visit. Each function also takes the customary @errp argument (see + * The visit_type_FOO() functions take a non-null @obj argument; they + * allocate *@obj during input visits, leave it unchanged during + * output and clone visits, and free it (recursively) during a dealloc + * visit. + * + * Each function also takes the customary @errp argument (see * qapi/error.h for details), for reporting any errors (such as if a * member @name is not present, or is present but not the specified * type). * * If an error is detected during visit_type_FOO() with an input - * visitor, then *@obj will be NULL for pointer types, and left - * unchanged for scalar types. Using an output or clone visitor with - * an incomplete object has undefined behavior (other than a special - * case for visit_type_str() treating NULL like ""), while the dealloc - * visitor safely handles incomplete objects. Since input visitors - * never produce an incomplete object, such an object is possible only - * by manual construction. + * visitor, then *@obj will be set to NULL for pointer types, and left + * unchanged for scalar types. + * + * Using an output or clone visitor with an incomplete object has + * undefined behavior (other than a special case for visit_type_str() + * treating NULL like ""), while the dealloc visitor safely handles + * incomplete objects. Since input visitors never produce an + * incomplete object, such an object is possible only by manual + * construction. * * For the QAPI object types (structs, unions, and alternates), there * is an additional generated function in qapi-visit-MODULE.h @@ -100,23 +110,20 @@ * * void qapi_free_FOO(FOO *obj); * - * where behaves like free() in that @obj may be NULL. Such objects - * may also be used with the following macro, provided alongside the - * clone visitor: + * Does nothing when @obj is NULL. + * + * Such objects may also be used with macro * * Type *QAPI_CLONE(Type, src); * - * in order to perform a deep clone of @src. Because of the generated - * qapi_free functions and the QAPI_CLONE() macro, the clone and - * dealloc visitor should not be used directly outside of QAPI code. + * in order to perform a deep clone of @src. * - * QAPI types can also inherit from a base class; when this happens, a - * function is generated for easily going from the derived type to the - * base type: + * For QAPI types can that inherit from a base type, a function is + * generated for going from the derived type to the base type: * * BASE *qapi_CHILD_base(CHILD *obj); * - * For a real QAPI struct, typical input usage involves: + * Typical input visitor usage involves: * * * Foo *f; @@ -153,7 +160,7 @@ * qapi_free_FooList(l); * * - * Similarly, typical output usage is: + * Typical output visitor usage: * * * Foo *f = ...obtain populated object... @@ -172,17 +179,8 @@ * visit_free(v); * * - * When visiting a real QAPI struct, this file provides several - * helpers that rely on in-tree information to control the walk: - * visit_optional() for the 'has_member' field associated with - * optional 'member' in the C struct; and visit_next_list() for - * advancing through a FooList linked list. Similarly, the - * visit_is_input() helper makes it possible to write code that is - * visitor-agnostic everywhere except for cleanup. Only the generated - * visit_type functions need to use these helpers. - * * It is also possible to use the visitors to do a virtual walk, where - * no actual QAPI struct is present. In this situation, decisions + * no actual QAPI object is present. In this situation, decisions * about what needs to be walked are made by the calling code, and * structured visits are split between pairs of start and end methods * (where the end method must be called if the start function @@ -227,6 +225,12 @@ * out: * visit_free(v); * + * + * This file provides helpers for use by the generated + * visit_type_FOO(): visit_optional() for the 'has_member' field + * associated with optional 'member' in the C struct, + * visit_next_list() for advancing through a FooList linked list, and + * visit_is_input() for cleaning up on failure. */ /*** Useful types ***/ -- cgit v1.1 From 8e08bf4ea24c3e6e07fab2c1b5bdcc7b104012c4 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:29 +0200 Subject: qapi: Assert incomplete object occurs only in dealloc visitor Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-7-armbru@redhat.com> --- include/qapi/visitor.h | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'include') diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index a425ea5..2d40d2f 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -479,6 +479,11 @@ void visit_type_enum(Visitor *v, const char *name, int *obj, */ bool visit_is_input(Visitor *v); +/* + * Check if visitor is a dealloc visitor. + */ +bool visit_is_dealloc(Visitor *v); + /*** Visiting built-in types ***/ /* -- cgit v1.1 From 8b7ce95b46815f274aed52857260cb180f6fade3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:30 +0200 Subject: qapi: Fix Visitor contract for start_alternate() The contract demands v->start_alternate() for input and dealloc visitors, but visit_start_alternate() actually requires it for input and clone visitors. Fix the contract, and delete superfluous qapi_dealloc_start_alternate(). Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-8-armbru@redhat.com> --- include/qapi/visitor-impl.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor-impl.h b/include/qapi/visitor-impl.h index 8ccb3b6..252206d 100644 --- a/include/qapi/visitor-impl.h +++ b/include/qapi/visitor-impl.h @@ -67,13 +67,12 @@ struct Visitor /* Must be set */ void (*end_list)(Visitor *v, void **list); - /* Must be set by input and dealloc visitors to visit alternates; - * optional for output visitors. */ + /* Must be set by input and clone visitors to visit alternates */ void (*start_alternate)(Visitor *v, const char *name, GenericAlternate **obj, size_t size, Error **errp); - /* Optional, needed for dealloc visitor */ + /* Optional */ void (*end_alternate)(Visitor *v, void **obj); /* Must be set */ -- cgit v1.1 From 1f5842487ad5b3d59ea32742e30dc7441f413e6c Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 24 Apr 2020 10:43:35 +0200 Subject: qapi: Only input visitors can actually fail The previous few commits have made this more obvious, and removed the one exception. Time to clarify the documentation, and drop dead error checking. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20200424084338.26803-13-armbru@redhat.com> --- include/qapi/visitor-impl.h | 4 ++++ include/qapi/visitor.h | 40 ++++++++++++++++++++++++---------------- 2 files changed, 28 insertions(+), 16 deletions(-) (limited to 'include') diff --git a/include/qapi/visitor-impl.h b/include/qapi/visitor-impl.h index 252206d..98dc533 100644 --- a/include/qapi/visitor-impl.h +++ b/include/qapi/visitor-impl.h @@ -43,6 +43,10 @@ typedef enum VisitorType { struct Visitor { + /* + * Only input visitors may fail! + */ + /* Must be set to visit structs */ void (*start_struct)(Visitor *v, const char *name, void **obj, size_t size, Error **errp); diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h index 2d40d2f..5573906 100644 --- a/include/qapi/visitor.h +++ b/include/qapi/visitor.h @@ -82,7 +82,7 @@ * Each function also takes the customary @errp argument (see * qapi/error.h for details), for reporting any errors (such as if a * member @name is not present, or is present but not the specified - * type). + * type). Only input visitors can fail. * * If an error is detected during visit_type_FOO() with an input * visitor, then *@obj will be set to NULL for pointer types, and left @@ -164,19 +164,14 @@ * * * Foo *f = ...obtain populated object... - * Error *err = NULL; * Visitor *v; * Type *result; * * v = FOO_visitor_new(..., &result); - * visit_type_Foo(v, NULL, &f, &err); - * if (err) { - * ...handle error... - * } else { - * visit_complete(v, &result); - * ...use result... - * } + * visit_type_Foo(v, NULL, &f, &error_abort); + * visit_complete(v, &result); * visit_free(v); + * ...use result... * * * It is also possible to use the visitors to do a virtual walk, where @@ -289,6 +284,7 @@ void visit_free(Visitor *v); * case @size is ignored. * * On failure, set *@obj to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. * * After visit_start_struct() succeeds, the caller may visit its * members one after the other, passing the member's name and address @@ -305,7 +301,8 @@ void visit_start_struct(Visitor *v, const char *name, void **obj, /* * Prepare for completing an object visit. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. * * Should be called prior to visit_end_struct() if all other * intermediate visit steps were successful, to allow the visitor one @@ -342,6 +339,7 @@ void visit_end_struct(Visitor *v, void **obj); * ignored. * * On failure, set *@list to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. * * After visit_start_list() succeeds, the caller may visit its members * one after the other. A real visit (where @list is non-NULL) uses @@ -375,7 +373,8 @@ GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size); /* * Prepare for completing a list visit. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. * * Should be called prior to visit_end_list() if all other * intermediate visit steps were successful, to allow the visitor one @@ -411,6 +410,7 @@ void visit_end_list(Visitor *v, void **list); * (*@obj)->type. Other visitors leave @obj unchanged. * * On failure, set *@obj to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. * * If successful, this must be paired with visit_end_alternate() with * the same @obj to clean up, even if visiting the contents of the @@ -465,11 +465,13 @@ bool visit_optional(Visitor *v, const char *name, bool *present); * visitors produce text output. The mapping between enumeration * values and strings is done by the visitor core, using @lookup. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. * * May call visit_type_str() under the hood, and the enum visit may * fail even if the corresponding string visit succeeded; this implies - * that visit_type_str() must have no unwelcome side effects. + * that an input visitor's visit_type_str() must have no unwelcome + * side effects. */ void visit_type_enum(Visitor *v, const char *name, int *obj, const QEnumLookup *lookup, Error **errp); @@ -495,7 +497,8 @@ bool visit_is_dealloc(Visitor *v); * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. */ void visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp); @@ -573,7 +576,8 @@ void visit_type_size(Visitor *v, const char *name, uint64_t *obj, * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. */ void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); @@ -592,6 +596,7 @@ void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); * into @obj for use by an output visitor. * * On failure, set *@obj to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. * * FIXME: Callers that try to output NULL *obj should not be allowed. */ @@ -607,7 +612,8 @@ void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp); * other visitors will leave *@obj unchanged. Visitors should * document if infinity or NaN are not permitted. * - * On failure, store an error through @errp. + * On failure, store an error through @errp. Can happen only when @v + * is an input visitor. */ void visit_type_number(Visitor *v, const char *name, double *obj, Error **errp); @@ -623,6 +629,7 @@ void visit_type_number(Visitor *v, const char *name, double *obj, * for output visitors. * * On failure, set *@obj to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. * * Note that some kinds of input can't express arbitrary QObject. * E.g. the visitor returned by qobject_input_visitor_new_keyval() @@ -640,6 +647,7 @@ void visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp); * other visitors ignore *@obj. * * On failure, set *@obj to NULL and store an error through @errp. + * Can happen only when @v is an input visitor. */ void visit_type_null(Visitor *v, const char *name, QNull **obj, Error **errp); -- cgit v1.1