error: Document how to accumulate multiple errors

Suggested-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 include/qapi/error.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

On Tue, Nov 17, 2015 at 05:05:49PM +0100, Markus Armbruster wrote:
> Suggested-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Reviewed-by: Eric Blake <eblake@redhat.com>
> ---
>  include/qapi/error.h | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

On Tue, 11/17 17:05, Markus Armbruster wrote:
> Suggested-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Reviewed-by: Eric Blake <eblake@redhat.com>
> ---
>  include/qapi/error.h | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/include/qapi/error.h b/include/qapi/error.h
> index 4d42cdc..b2362a5 100644
> --- a/include/qapi/error.h
> +++ b/include/qapi/error.h
> @@ -76,6 +76,23 @@
>   * But when all you do with the error is pass it on, please use
>   *     foo(arg, errp);
>   * for readability.
> + *
> + * Receive and accumulate multiple errors (first one wins):
> + *     Error *err = NULL, *local_err = NULL;
> + *     foo(arg, &err);
> + *     bar(arg, &local_err);
> + *     error_propagate(&err, local_err);
> + *     if (err) {
> + *         handle the error...
> + *     }
> + *
> + * Do *not* "optimize" this to
> + *     foo(arg, &err);
> + *     bar(arg, &err); // WRONG!
> + *     if (err) {
> + *         handle the error...
> + *     }
> + * because this may pass a non-null err to bar().
>   */
>  
>  #ifndef ERROR_H
> -- 
> 2.4.3
> 
> 

Curious if there is a recommended way to report both error messages to caller,
rather than overwriting the first with the second?

Fam

Fam Zheng <famz@redhat.com> writes:

> On Tue, 11/17 17:05, Markus Armbruster wrote:
>> Suggested-by: Eric Blake <eblake@redhat.com>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> Reviewed-by: Eric Blake <eblake@redhat.com>
>> ---
>>  include/qapi/error.h | 17 +++++++++++++++++
>>  1 file changed, 17 insertions(+)
>> 
>> diff --git a/include/qapi/error.h b/include/qapi/error.h
>> index 4d42cdc..b2362a5 100644
>> --- a/include/qapi/error.h
>> +++ b/include/qapi/error.h
>> @@ -76,6 +76,23 @@
>>   * But when all you do with the error is pass it on, please use
>>   *     foo(arg, errp);
>>   * for readability.
>> + *
>> + * Receive and accumulate multiple errors (first one wins):
>> + *     Error *err = NULL, *local_err = NULL;
>> + *     foo(arg, &err);
>> + *     bar(arg, &local_err);
>> + *     error_propagate(&err, local_err);
>> + *     if (err) {
>> + *         handle the error...
>> + *     }
>> + *
>> + * Do *not* "optimize" this to
>> + *     foo(arg, &err);
>> + *     bar(arg, &err); // WRONG!
>> + *     if (err) {
>> + *         handle the error...
>> + *     }
>> + * because this may pass a non-null err to bar().
>>   */
>>  
>>  #ifndef ERROR_H
>> -- 
>> 2.4.3
>> 
>> 
>
> Curious if there is a recommended way to report both error messages to caller,
> rather than overwriting the first with the second?

The documentation above is about keeping the first and throwing away the
second, i.e. first one wins.  I haven't seen in "last one wins" the
code, yet.  How to do it is thus left as exercise to the reader.

You can only return one *error*.  You can still combine multiple
*messages* into one error.  There is no recommended way, at least not
yet.

You could use the hint mechanism to append additional messages:

    foo(arg, &err);
    bar(arg, &err2);
    if (err2) {
        error_append_hint(err, "additionally, %s", error_get_pretty(err2));
        error_free(err2);
    }

Just an example, the wording of the hint is probably not a good idea.

You may want to modify the first message, too.  The obvious technique
for receiving, modifying and passing on an error:

    frob(arg, &err)
    error_setg(errp, "Could not frobnicate: %s",
               error_get_pretty(local_err));