[Bug tree-optimization/88793] New: Document that __attribute__ ((cold)) is not equivalent to __builtin_except because of optimization for size

[fw at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=88793

            Bug ID: 88793
           Summary: Document that __attribute__ ((cold)) is not equivalent
                    to __builtin_except because of optimization for size
           Product: gcc
           Version: 9.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: tree-optimization
          Assignee: unassigned at gcc dot gnu.org
          Reporter: fw at gcc dot gnu.org
  Target Milestone: ---

The documentation says this:

'cold'
     The 'cold' attribute on functions is used to inform the compiler
     that the function is unlikely to be executed.  The function is
     optimized for size rather than speed and on many targets it is
     placed into a special subsection of the text section so all cold
     functions appear close together, improving code locality of
     non-cold parts of program.  The paths leading to calls of cold
     functions within code are marked as unlikely by the branch
     prediction mechanism.  It is thus useful to mark functions used to
     handle unlikely conditions, such as 'perror', as cold to improve
     optimization of hot functions that do call marked functions in rare
     occasions.

However, optimizing for size is a very big hammer and causes substantial
performance issues on i386 and x86-64 due to string function inlining.  As a
result, the cold attribute is only suitable for code that is basically never
executed.  For other cases, like repeated execution which only happens in an
unlikely configuration, it is inappropriate.  The documentation does not make
this clear enough, and programmers use __attribute__ ((cold)) and the
propagation into call sites as a more convenient alternative for
__builtin_expect, leading to performance issues.

The referenced downstream bug concerns some old GCC version where GCC
incorrectly inferred cold code regions from __builtin_expect.  I'm including it
here to indicate that the distinction matters in practice.