Re: [PATCH 02/46] error: Document Error API usage rules

[Markus Armbruster]

Greg Kurz <groug@kaod.org> writes:

> On Wed, 24 Jun 2020 18:43:00 +0200
> Markus Armbruster <armbru@redhat.com> wrote:
>
>> 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.
>> 
>
> This confusion is reinforced by the fact that the standard pattern:
>
>     error_setg(errp, ...);
>     error_append_hint(errp, ...);
>
> doesn't work when errp is &error_fatal, which is a typical case of
> an invalid command line argument, where it is valuable to suggest
> something sensible to the user but error_setg() exits before we
> could do so.
>
> Fortunately, Vladimir's work will address that and eliminate the
> temptation to workaround the issue with more boilerplate :)

Yes, my work does not obviate Vladimir's at all.  It merely reduce the
number of auto-propagations, hopefully making his patches slightly less
scary.

>> 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: Greg Kurz <groug@kaod.org>

Thanks!