motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-01 23:03:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: Add new visit_complete() function

Browse source 
Making each output visitor provide its own output collection
function was the only remaining reason for exposing visitor
sub-types to the rest of the code base.  Add a polymorphic
visit_complete() function which is a no-op for input visitors,
and which populates an opaque pointer for output visitors.  For
maximum type-safety, also add a parameter to the output visitor
constructors with a type-correct version of the output pointer,
and assert that the two uses match.

This approach was considered superior to either passing the
output parameter only during construction (action at a distance
during visit_free() feels awkward) or only during visit_complete()
(defeating type safety makes it easier to use incorrectly).

Most callers were function-local, and therefore a mechanical
conversion; the testsuite was a bit trickier, but the previous
cleanup patch minimized the churn here.

The visit_complete() function may be called at most once; doing
so lets us use transfer semantics rather than duplication or
ref-count semantics to get the just-built output back to the
caller, even though it means our behavior is not idempotent.

Generated code is simplified as follows for events:

|@@ -26,7 +26,7 @@ void qapi_event_send_acpi_device_ost(ACP
|     QDict *qmp;
|     Error *err = NULL;
|     QMPEventFuncEmit emit;
|-    QmpOutputVisitor *qov;
|+    QObject *obj;
|     Visitor *v;
|     q_obj_ACPI_DEVICE_OST_arg param = {
|         info
|@@ -39,8 +39,7 @@ void qapi_event_send_acpi_device_ost(ACP
|
|     qmp = qmp_event_build_dict("ACPI_DEVICE_OST");
|
|-    qov = qmp_output_visitor_new();
|-    v = qmp_output_get_visitor(qov);
|+    v = qmp_output_visitor_new(&obj);
|
|     visit_start_struct(v, "ACPI_DEVICE_OST", NULL, 0, &err);
|     if (err) {
|@@ -55,7 +54,8 @@ void qapi_event_send_acpi_device_ost(ACP
|         goto out;
|     }
|
|-    qdict_put_obj(qmp, "data", qmp_output_get_qobject(qov));
|+    visit_complete(v, &obj);
|+    qdict_put_obj(qmp, "data", obj);
|     emit(QAPI_EVENT_ACPI_DEVICE_OST, qmp, &err);

and for commands:

| {
|     Error *err = NULL;
|-    QmpOutputVisitor *qov = qmp_output_visitor_new();
|     Visitor *v;
|
|-    v = qmp_output_get_visitor(qov);
|+    v = qmp_output_visitor_new(ret_out);
|     visit_type_AddfdInfo(v, "unused", &ret_in, &err);
|-    if (err) {
|-        goto out;
|+    if (!err) {
|+        visit_complete(v, ret_out);
|     }
|-    *ret_out = qmp_output_get_qobject(qov);
|-
|-out:
|     error_propagate(errp, err);

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1465490926-28625-13-git-send-email-eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Eric Blake 2016-06-09 10:48:43 -06:00 • committed by Markus Armbruster
parent 23d1705f42
commit 3b098d5697
23 changed files with 166 additions and 160 deletions
Download patch file Download diff file Expand all files Collapse all files

50
include/qapi/visitor.h
View file

@ -39,21 +39,15 @@
*
* All of the visitors are created via:
*
* Type *subtype_visitor_new(parameters...);
*
* where Type is either directly 'Visitor *', or is a subtype that can
* be trivially upcast to Visitor * via another function:
*
* Visitor *subtype_get_visitor(SubtypeVisitor *);
* Visitor *subtype_visitor_new(parameters...);
*
* A visitor should be used for exactly one top-level visit_type_FOO()
* or virtual walk, then passed to visit_free() to clean up resources.
* 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. Output visitors
* provide an additional function, for collecting the final results of
* a successful visit: string_output_get_string() and
* qmp_output_get_qobject(); this collection function should not be
* called if any errors were reported during the visit.
* some other error is detected in the meantime.
*
* All QAPI types have a corresponding function with a signature
* roughly compatible with this:
@ -123,14 +117,14 @@
* Error *err = NULL;
* Visitor *v;
*
* v = ...obtain input visitor...
* v = FOO_visitor_new(...);
* visit_type_Foo(v, NULL, &f, &err);
* if (err) {
* ...handle error...
* } else {
* ...use f...
* }
* ...clean up v...
* visit_free(v);
* qapi_free_Foo(f);
* </example>
*
@ -140,7 +134,7 @@
* Error *err = NULL;
* Visitor *v;
*
* v = ...obtain input visitor...
* v = FOO_visitor_new(...);
* visit_type_FooList(v, NULL, &l, &err);
* if (err) {
* ...handle error...
@ -149,7 +143,7 @@
* ...use l->value...
* }
* }
* ...clean up v...
* visit_free(v);
* qapi_free_FooList(l);
* </example>
*
@ -159,13 +153,17 @@
* Foo *f = ...obtain populated object...
* Error *err = NULL;
* Visitor *v;
* Type *result;
*
* v = ...obtain output visitor...
* v = FOO_visitor_new(..., &result);
* visit_type_Foo(v, NULL, &f, &err);
* if (err) {
* ...handle error...
* } else {
* visit_complete(v, &result);
* ...use result...
* }
* ...clean up v...
* visit_free(v);
* </example>
*
* When visiting a real QAPI struct, this file provides several
@ -191,7 +189,7 @@
* Error *err = NULL;
* int value;
*
* v = ...obtain visitor...
* v = FOO_visitor_new(...);
* visit_start_struct(v, NULL, NULL, 0, &err);
* if (err) {
* goto out;
@ -219,7 +217,7 @@
* visit_end_struct(v, NULL);
* out:
* error_propagate(errp, err);
* ...clean up v...
* visit_free(v);
* </example>
*/
@ -242,6 +240,18 @@ typedef struct GenericAlternate {
/*** Visitor cleanup ***/
/*
* Complete the visit, collecting any output.
*
* May only be called only once after a successful top-level
* visit_type_FOO() or visit_end_ITEM(), and marks the end of the
* visit. The @opaque pointer should match the output parameter
* passed to the subtype_visitor_new() used to create an output
* visitor, or NULL for any other visitor. Needed for output
* visitors, but may also be called with other visitors.
*/
void visit_complete(Visitor *v, void *opaque);
/*
* Free @v and any resources it has tied up.
*