Fix usage of error_append_hint()

[Qemu-devel] [PATCH 01/17] error: Update error_append_hint()'s documentation

Greg Kurz posted 17 patches 6 years, 1 month ago

Download mbox

Maintainers: Yuval Shaia <yuval.shaia@oracle.com>, Eric Blake <eblake@redhat.com>, "Dr. David Alan Gilbert" <dgilbert@redhat.com>, Halil Pasic <pasic@linux.ibm.com>, Markus Armbruster <armbru@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, David Gibson <david@gibson.dropbear.id.au>, John Snow <jsnow@redhat.com>, Fam Zheng <fam@euphon.net>, Richard Henderson <rth@twiddle.net>, Jeff Cody <codyprime@gmail.com>, Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>, Gerd Hoffmann <kraxel@redhat.com>, Max Reitz <mreitz@redhat.com>, Subbaraya Sundeep <sundeep.lkml@gmail.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Eric Farman <farman@linux.ibm.com>, Peter Maydell <peter.maydell@linaro.org>, Paolo Bonzini <pbonzini@redhat.com>, Christian Borntraeger <borntraeger@de.ibm.com>, Juan Quintela <quintela@redhat.com>, Alex Williamson <alex.williamson@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Michael Roth <mdroth@linux.vnet.ibm.com>, David Hildenbrand <david@redhat.com>, Cornelia Huck <cohuck@redhat.com>

Expand all Fold all

[Qemu-devel] [PATCH 01/17] error: Update error_append_hint()'s documentation

Posted by Greg Kurz 6 years, 1 month ago

error_setg() and error_propagate(), as well as their variants, cause
QEMU to terminate when called with &error_fatal or &error_abort. This
prevents to add hints since error_append_hint() isn't even called in
this case.

It means that error_append_hint() should only be used with a local
error object, and then propagate this local error to the caller.

Document this in <qapi/error.h> .

Signed-off-by: Greg Kurz <groug@kaod.org>
---
 include/qapi/error.h |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 3f95141a01a8..28174329ba71 100644
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -27,6 +27,13 @@
  *     error_setg(&err, "invalid quark\n"
  *                "Valid quarks are up, down, strange, charm, top, bottom.");
  *
+ * Dot *not* pass the errp parameter from the caller
+ *     error_setg(errp, "invalid quark");
+ *     error_append_hint(errp, "Valid quarks are up, down, strange, "
+ *                       "charm, top, bottom.\n");
+ * because error_setg() terminates QEMU if @errp is &error_fatal or
+ * &error_abort, and the hints are not even added.
+ *
  * Report an error to the current monitor if we have one, else stderr:
  *     error_report_err(err);
  * This frees the error object.
@@ -252,7 +259,9 @@ void error_prepend(Error **errp, const char *fmt, ...)
  * error message.
  * @errp may be NULL, but not &error_fatal or &error_abort.
  * Trivially the case if you call it only after error_setg() or
- * error_propagate().
+ * error_propagate(). CAUTION: error_setg() and error_propagate() do
+ * not return when passed &error_fatal. Always use a local error object
+ * and propagate it to the caller.
  * May be called multiple times.  The resulting hint should end with a
  * newline.
  */

Re: [Qemu-devel] [PATCH 01/17] error: Update error_append_hint()'s documentation

Posted by Cornelia Huck 6 years, 1 month ago

On Tue, 17 Sep 2019 12:20:37 +0200
Greg Kurz <groug@kaod.org> wrote:

> error_setg() and error_propagate(), as well as their variants, cause
> QEMU to terminate when called with &error_fatal or &error_abort. This
> prevents to add hints since error_append_hint() isn't even called in
> this case.
> 
> It means that error_append_hint() should only be used with a local
> error object, and then propagate this local error to the caller.
> 
> Document this in <qapi/error.h> .
> 
> Signed-off-by: Greg Kurz <groug@kaod.org>
> ---
>  include/qapi/error.h |   11 ++++++++++-

It's a bit awkward requiring a local object, but better safe than sorry.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

Re: [Qemu-devel] [PATCH 01/17] error: Update error_append_hint()'s documentation

Posted by Eric Blake 6 years, 1 month ago

On 9/17/19 5:20 AM, Greg Kurz wrote:
> error_setg() and error_propagate(), as well as their variants, cause
> QEMU to terminate when called with &error_fatal or &error_abort. This
> prevents to add hints since error_append_hint() isn't even called in

s/to add/adding/

> this case.
> 
> It means that error_append_hint() should only be used with a local
> error object, and then propagate this local error to the caller.
> 
> Document this in <qapi/error.h> .
> 
> Signed-off-by: Greg Kurz <groug@kaod.org>
> ---
>  include/qapi/error.h |   11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org