git: ecfe30854204 - stable/14 - style(9): Add comments about branch prediction

The branch stable/14 has been updated by brooks:

URL: https://cgit.FreeBSD.org/src/commit/?id=ecfe30854204e8de29ae637d493bd9de689ababa

commit ecfe30854204e8de29ae637d493bd9de689ababa
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2024-07-03 18:52:38 +0000
Commit:     Brooks Davis <brooks@FreeBSD.org>
CommitDate: 2024-12-13 21:34:08 +0000

    style(9): Add comments about branch prediction
    
    This is a partial merge of:
    
    cdefs.h: Add back comment about branch prediction
    
    Add back, with editing, the comments about branch prediction, when to
    use it, etc. Offer stronger opinions about this in style(9). Add in the
    convention for FreeBSD that we do only the entire expression in the if
    expression. Advise use only when it makes things measurably faster.
    
    Requested by:           jhb
    Sponsored by:           Netflix
    Reviewed by:            brooks, jhb
    Differential Revision:  https://reviews.freebsd.org/D45837
    
    (cherry picked from commit fd31c0946ee2240491db1301c2d33eb846221a54)
---
 share/man/man9/style.9 | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index a4ff85a07bcd..2e7c614b2a6d 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -908,6 +908,22 @@ New code should use
 .Fn _Static_assert
 instead of the older
 .Fn CTASSERT .
+.Pp
+.Fn __predict_true
+and
+.Fn __predict_false
+should only be used in frequently executed code when it makes the code
+measurably faster.
+It is wasteful to make predictions for infrequently run code, like subsystem
+initialization.
+When using branch prediction hints, atypical error conditions should use
+.Fn __predict_false
+(document the exceptions).
+Operations that almost always succeed use
+.Fn __predict_true .
+Only use the annotation for the entire if statement, rather than individual clauses.
+Do not add these annotations without empirical evidence of the likelihood of the
+branch.
 .Sh FILES
 .Bl -tag -width indent
 .It Pa /usr/src/tools/build/checkstyle9.pl