[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors
From: |
Daniel P. Berrange |
Subject: |
Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors |
Date: |
Mon, 23 Nov 2015 18:51:16 +0000 |
User-agent: |
Mutt/1.5.23 (2015-06-09) |
On Mon, Nov 23, 2015 at 07:41:24PM +0100, Lluís Vilanova wrote:
> Gives some general guidelines for reporting errors in QEMU.
>
> Signed-off-by: Lluís Vilanova <address@hidden>
> ---
> HACKING | 31 +++++++++++++++++++++++++++++++
> 1 file changed, 31 insertions(+)
>
> diff --git a/HACKING b/HACKING
> index 12fbc8a..e59bc34 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -157,3 +157,34 @@ painful. These are:
> * you may assume that integers are 2s complement representation
> * you may assume that right shift of a signed integer duplicates
> the sign bit (ie it is an arithmetic shift, not a logical shift)
> +
> +7. Error reporting
> +
> +QEMU provides two different mechanisms for reporting errors. You should use
> one
> +of these mechanisms instead of manually reporting them (i.e., do not use
> +'printf', 'exit' or 'abort').
> +
> +7.1. Errors in user inputs
> +
> +QEMU provides the functions in "include/qemu/error-report.h" to report errors
> +related to inputs provided by the user (e.g., command line arguments or
> +configuration files).
> +
> +These functions generate error messages with a uniform format that can
> reference
> +a location on the offending input.
> +
> +7.2. Other errors
> +
> +QEMU provides the functions in "include/qapi/error.h" to report other types
> of
> +errors (i.e., not triggered by command line arguments or configuration
> files).
> +
> +Functions in this header are used to accumulate error messages in an 'Error'
> +object, which can be propagated up the call chain where it is finally
> reported.
> +
> +In its simplest form, you can immediately report an error with:
> +
> + error_setg(&error_warn, "Error with %s", "arguments");
> +
> +See the "include/qapi/error.h" header for additional convenience functions
> and
> +special arguments. Specially, see 'error_fatal' and 'error_abort' to show
> errors
> +and immediately terminate QEMU.
I don't think this "Errors in user inputs" vs "Other errors" distinction
really makes sense. Whether an error raised in a piece of code is related
to user input or not is almost impossible to determine in practice. So as
a rule to follow it is not practical.
AFAIK, include/qemu/error-report.h is the historical failed experiment
in structured error reporting, while include/qapi/error.h is the new
preferred error reporting system that everything should be using.
On this basis, I'd simply say that include/qemu/error-report.h is
legacy code that should no longer be used, and that new code should
use include/qapi/error.h exclusively and existing code converted
where practical.
Regards,
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://autobuild.org -o- http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
- [Qemu-devel] [RFC][PATCH v2 0/2] utils: Improve and document error reporting, Lluís Vilanova, 2015/11/23
- [Qemu-devel] [PATCH v2 1/2] utils: Add warning messages, Lluís Vilanova, 2015/11/23
- [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors, Lluís Vilanova, 2015/11/23
- Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors,
Daniel P. Berrange <=
- Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors, Markus Armbruster, 2015/11/24
- Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors, Lluís Vilanova, 2015/11/24
- Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors, Markus Armbruster, 2015/11/24