The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=fd31c0946ee2240491db1301c2d33eb846221a54
commit fd31c0946ee2240491db1301c2d33eb846221a54 Author: Warner Losh <[email protected]> AuthorDate: 2024-07-03 18:52:38 +0000 Commit: Warner Losh <[email protected]> CommitDate: 2024-07-03 18:56:42 +0000 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 --- share/man/man9/style.9 | 16 ++++++++++++++++ sys/sys/cdefs.h | 7 +++++++ 2 files changed, 23 insertions(+) diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index 381f3aa3bfa3..daddc57bfb1f 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -897,6 +897,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 diff --git a/sys/sys/cdefs.h b/sys/sys/cdefs.h index 7c4890ece8d5..b92992c1b5c3 100644 --- a/sys/sys/cdefs.h +++ b/sys/sys/cdefs.h @@ -321,6 +321,13 @@ #define __restrict restrict #endif +/* + * All modern compilers have explicit branch prediction so that the CPU back-end + * can hint to the processor and also so that code blocks can be reordered such + * that the predicted path sees a more linear flow, thus improving cache + * behavior, etc. Use sparingly, except in performance critical code where + * they make things measurably faster. + */ #define __predict_true(exp) __builtin_expect((exp), 1) #define __predict_false(exp) __builtin_expect((exp), 0)
