[v2] Less clumsy error checking

[PATCH v2 02/44] error: Document Error API usage rules

Markus Armbruster posted 44 patches 5 years, 7 months ago

Diff against v1 v3 v4
Download mbox

Maintainers: Andrey Smirnov <andrew.smirnov@gmail.com>, Antony Pavlov <antonynpavlov@gmail.com>, Eric Blake <eblake@redhat.com>, Matthew Rosato <mjrosato@linux.ibm.com>, John Snow <jsnow@redhat.com>, Jason Wang <jasowang@redhat.com>, Richard Henderson <rth@twiddle.net>, Kevin Wolf <kwolf@redhat.com>, Paul Burton <pburton@wavecomp.com>, Artyom Tarasenko <atar4qemu@gmail.com>, Zhang Chen <chen.zhang@intel.com>, "Michael S. Tsirkin" <mst@redhat.com>, Cornelia Huck <cohuck@redhat.com>, Paul Durrant <paul@xen.org>, Christian Borntraeger <borntraeger@de.ibm.com>, David Hildenbrand <david@redhat.com>, Stefan Hajnoczi <stefanha@redhat.com>, Max Reitz <mreitz@redhat.com>, "Dr. David Alan Gilbert" <dgilbert@redhat.com>, Joel Stanley <joel@jms.id.au>, Igor Mammedov <imammedo@redhat.com>, Andrew Baumann <Andrew.Baumann@microsoft.com>, Wen Congyang <wencongyang2@huawei.com>, Liu Yuan <namei.unix@gmail.com>, Laurent Vivier <lvivier@redhat.com>, Jeff Cody <codyprime@gmail.com>, Stefan Berger <stefanb@linux.ibm.com>, Riku Voipio <riku.voipio@iki.fi>, Ronnie Sahlberg <ronniesahlberg@gmail.com>, Ari Sundholm <ari@tuxera.com>, "Philippe Mathieu-Daudé" <philmd@redhat.com>, Jan Kiszka <jan.kiszka@web.de>, Michael Roth <mdroth@linux.vnet.ibm.com>, Alex Williamson <alex.williamson@redhat.com>, Li Zhijian <lizhijian@cn.fujitsu.com>, Beniamino Galvani <b.galvani@gmail.com>, Alistair Francis <alistair@alistair23.me>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, Stefan Weil <sw@weilnetz.de>, Yoshinori Sato <ysato@users.sourceforge.jp>, Aurelien Jarno <aurelien@aurel32.net>, "Gonglei (Arei)" <arei.gonglei@huawei.com>, Leif Lindholm <leif@nuviainc.com>, "Hervé Poussineau" <hpoussin@reactos.org>, "Edgar E. Iglesias" <edgar.iglesias@gmail.com>, Palmer Dabbelt <palmer@dabbelt.com>, Peter Lieven <pl@kamp.de>, Eric Auger <eric.auger@redhat.com>, Xiao Guangrong <xiaoguangrong.eric@gmail.com>, Alberto Garcia <berto@igalia.com>, Niek Linnenbank <nieklinnenbank@gmail.com>, Xie Changlong <xiechanglong.d@gmail.com>, Aleksandar Markovic <aleksandar.qemu.devel@gmail.com>, Markus Armbruster <armbru@redhat.com>, Stefano Stabellini <sstabellini@kernel.org>, Fam Zheng <fam@euphon.net>, "Daniel P. Berrangé" <berrange@redhat.com>, Sagar Karandikar <sagark@eecs.berkeley.edu>, Igor Mitsyanko <i.mitsyanko@gmail.com>, Gerd Hoffmann <kraxel@redhat.com>, Eduardo Habkost <ehabkost@redhat.com>, Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Peter Chubb <peter.chubb@nicta.com.au>, "Denis V. Lunev" <den@openvz.org>, Halil Pasic <pasic@linux.ibm.com>, Anthony Perard <anthony.perard@citrix.com>, Andrew Jeffery <andrew@aj.id.au>, Jason Dillaman <dillaman@redhat.com>, Rob Herring <robh@kernel.org>, "Richard W.M. Jones" <rjones@redhat.com>, "Cédric Le Goater" <clg@kaod.org>, Subbaraya Sundeep <sundeep.lkml@gmail.com>, Peter Maydell <peter.maydell@linaro.org>, Aleksandar Rikalo <aleksandar.rikalo@syrmia.com>, Jean-Christophe Dubois <jcd@tribudubois.net>, David Gibson <david@gibson.dropbear.id.au>, Bastian Koppelmann <kbastian@mail.uni-paderborn.de>, Radoslaw Biernacki <radoslaw.biernacki@linaro.org>, Thomas Huth <thuth@redhat.com>, Amit Shah <amit@kernel.org>, Paolo Bonzini <pbonzini@redhat.com>

There is a newer version of this series

Expand all Fold all

[PATCH v2 02/44] error: Document Error API usage rules

Posted by Markus Armbruster 5 years, 7 months ago

This merely codifies existing practice, with one exception: the rule
advising against returning void, where existing practice is mixed.

When the Error API was created, we adopted the (unwritten) rule to
return void when the function returns no useful value on success,
unlike GError, which recommends to return true on success and false on
error then.

When a function returns a distinct error value, say false, a checked
call that passes the error up looks like

    if (!frobnicate(..., errp)) {
        handle the error...
    }

When it returns void, we need

    Error *err = NULL;

    frobnicate(..., &err);
    if (err) {
        handle the error...
        error_propagate(errp, err);
    }

Not only is this more verbose, it also creates an Error object even
when @errp is null, &error_abort or &error_fatal.

People got tired of the additional boilerplate, and started to ignore
the unwritten rule.  The result is confusion among developers about
the preferred usage.

The written rule will hopefully reduce the confusion.

The remainder of this series will update a substantial amount of code
to honor the rule.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Reviewed-by: Greg Kurz <groug@kaod.org>
---
 include/qapi/error.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 3e64324b7a..5ceb3ace06 100644
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -15,6 +15,32 @@
 /*
  * Error reporting system loosely patterned after Glib's GError.
  *
+ * Rules:
+ *
+ * - Functions that use Error to report errors have an Error **errp
+ *   parameter.  It should be the last parameter, except for functions
+ *   taking variable arguments.
+ *
+ * - You may pass NULL to not receive the error, &error_abort to abort
+ *   on error, &error_fatal to exit(1) on error, or a pointer to a
+ *   variable containing NULL to receive the error.
+ *
+ * - The value of @errp should not affect control flow.
+ *
+ * - On success, the function should not use @errp.  On failure, it
+ *   should set a new error, e.g. with error_setg(errp, ...), or
+ *   propagate an existing one, e.g. with error_propagate(errp, ...).
+ *
+ * - Whenever practical, also return a value that indicates success /
+ *   failure.  This can make the error checking more concise, and can
+ *   avoid useless error object creation and destruction.  Note that
+ *   we still have many functions returning void.  We recommend
+ *   • bool-valued functions return true on success / false on failure,
+ *   • pointer-valued functions return non-null / null pointer, and
+ *   • integer-valued functions return non-negative / negative.
+ *
+ * How to:
+ *
  * Create an error:
  *     error_setg(errp, "situation normal, all fouled up");
  *
-- 
2.26.2