Function attribute to indicate a likely (or unlikely) return value

[Gabriel Ravier]

On 7/25/21 7:33 PM, Dominique Pellé via Gcc wrote:
> Hi
>
> I read https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
> but was left wondering: is there a way to annotate a function
> to indicate that a return value is likely (or unlikely)?
>
> For example, let's say we have this function:
>
>    // Return OK (=0) in case of success (frequent case)
>    // or an error code != 0 in case of failure (rare case).
>    int do_something();
>
> If it's unlikely to fail, I wish I could declare the function like
> this (pseudo-code!):
>
>    int do_something() __likely_return(OK);
>
> So wherever it's used, the optimizer can optimize branch
> prediction and the instruction cache.  In other words, lines
> like this:
>
>    if (do_something() == OK)
>
> ...  would implicitly be similar to:
>
>    // LIKELY defined as __builtin_expect((x), 1).
>    if (LIKELY(do_something() == OK))
>
> The advantage of being able to annotate the declaration,
> is that we only need to annotate once in the header, and
> all uses of the function can benefit from the optimization
> without polluting/modifying all code where the function
> is called.
>
> Another example: a function that would be unlikely to
> return NULL could be declared as:
>
>    void *foo() __unlikely_returns(NULL);
>
> This last example would be a bit similar to the
> __attribute__((malloc)) since I read about it in the doc:
>
>> In addition, the GCC predicts that a function with
>> the attribute returns non-null in most cases.
> Of course __attribute__((malloc)) gives other guarantees
> (return value cannot alias any other pointer) so it's not
> equivalent.
>
> Would attribute __likely_return() and  __unlikely_return()
> make sense?
>
> Is there already a way to achieve this which I missed in
> the doc?

I'd assume this can be accomplished with a simple inline wrapper.

>
> Regards
> Dominique