P0479R5 Likely and unlikely attributes

Editorially add an example as requested by CWG

Fixes #1956

Author: zygoloid

source/declarations.tex

@@ -4029,6 +4029,66 @@
 \end{codeblock}
 \end{example}
 
+\rSec2[dcl.attr.likelihood]{Likelihood attributes}%
+\indextext{attribute!likely}
+\indextext{attribute!unlikely}
+
+\pnum
+The \grammarterm{attribute-token}s
+\tcode{likely} and \tcode{unlikely}
+may be applied to labels or statements.
+The \grammarterm{attribute-token}s
+\tcode{likely} and \tcode{unlikely}
+shall appear at most once in each \grammarterm{attribute-list}
+and no \grammarterm{attribute-argument-clause} shall be present.
+The \grammarterm{attribute-token} \tcode{likely}
+shall not appear in an \grammarterm{attribute-specifier-seq}
+that contains the \grammarterm{attribute-token} \tcode{unlikely}.
+
+\pnum
+\begin{note}
+The use of the \tcode{likely} attribute
+is intended to allow implementations to optimize for
+the case where paths of execution including it
+are arbitrarily more likely
+than any alternative path of execution
+that does not include such an attribute on a statement or label.
+The use of the \tcode{unlikely} attribute
+is intended to allow implementations to optimize for
+the case where paths of execution including it
+are arbitrarily more unlikely
+than any alternative path of execution
+that does not include such an attribute on a statement or label.
+A path of execution includes a label
+if and only if it contains a jump to that label.
+Excessive usage of either of these attributes
+is liable to result in performance degradation.
+\end{note}
+
+\pnum
+\begin{example}
+\begin{codeblock}
+void g(int);
+int f(int n) {
+  if (n > 5) [[unlikely]] {     // \tcode{n > 5} is considered to be arbitrarily unlikely
+    g(0);
+    return n * 2 + 1;
+  }
+
+  switch (n) {
+  case 1:
+    g(1);
+    [[fallthrough]];
+
+  [[likely]] case 2:            // \tcode{n == 3} is considered to be arbitrarily more
+    g(2);                       // likely than any other value of \tcode{n}
+    break;
+  }
+  return 3;
+}
+\end{codeblock}
+\end{example}
+
 \rSec2[dcl.attr.unused]{Maybe unused attribute}%
 \indextext{attribute!maybe unused}