mhd_predict.h (6748B)
1 /* SPDX-License-Identifier: LGPL-2.1-or-later OR (GPL-2.0-or-later WITH eCos-exception-2.0) */ 2 /* 3 This file is part of GNU libmicrohttpd. 4 Copyright (C) 2025 Evgeny Grin (Karlson2k) 5 6 GNU libmicrohttpd is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public 8 License as published by the Free Software Foundation; either 9 version 2.1 of the License, or (at your option) any later version. 10 11 GNU libmicrohttpd is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 Alternatively, you can redistribute GNU libmicrohttpd and/or 17 modify it under the terms of the GNU General Public License as 18 published by the Free Software Foundation; either version 2 of 19 the License, or (at your option) any later version, together 20 with the eCos exception, as follows: 21 22 As a special exception, if other files instantiate templates or 23 use macros or inline functions from this file, or you compile this 24 file and link it with other works to produce a work based on this 25 file, this file does not by itself cause the resulting work to be 26 covered by the GNU General Public License. However the source code 27 for this file must still be made available in accordance with 28 section (3) of the GNU General Public License v2. 29 30 This exception does not invalidate any other reasons why a work 31 based on this file might be covered by the GNU General Public 32 License. 33 34 You should have received copies of the GNU Lesser General Public 35 License and the GNU General Public License along with this library; 36 if not, see <https://www.gnu.org/licenses/>. 37 */ 38 39 /** 40 * @file src/mhd2/mhd_predict.h 41 * @brief Macros that provide the compiler with hints about 42 * the anticipated outcomes of conditional expressions. 43 * @author Karlson2k (Evgeny Grin) 44 */ 45 46 #ifndef MHD_PREDICT_H 47 #define MHD_PREDICT_H 1 48 49 #include "mhd_sys_options.h" 50 51 /** 52 * @defgroup mhd2_predict Branch prediction hints 53 * 54 * Internal helpers to annotate most probable branch outcomes. 55 * 56 * @warning Misusing prediction (marking the uncommon path as common) can harm 57 * performance. Measuring before and after is highly recommended. 58 * 59 * @see MHD_NO_PREDICT_COND 60 * 61 * @{ 62 */ 63 64 65 /** 66 * @def MHD_NO_PREDICT_COND 67 * 68 * When defined, disables all prediction hints regardless of compiler 69 * support, turning the macros into plain boolean expressions. 70 * 71 * This can be useful for benchmarking or debugging to assess the impact of 72 * branch prediction hints on a given workload and compiler. 73 */ 74 75 #ifdef MHD_NO_PREDICT_COND 76 # ifdef MHD_HAVE___BUILTIN_EXPECT_WITH_PROBABILITY 77 # undef MHD_HAVE___BUILTIN_EXPECT_WITH_PROBABILITY 78 # endif 79 # ifdef MHD_HAVE___BUILTIN_EXPECT 80 # undef MHD_HAVE___BUILTIN_EXPECT 81 # endif 82 #else 83 # ifdef __has_builtin 84 # if ! defined(MHD_HAVE___BUILTIN_EXPECT_WITH_PROBABILITY) && \ 85 __has_builtin (__builtin_expect_with_probability) 86 # define MHD_HAVE___BUILTIN_EXPECT_WITH_PROBABILITY 1 87 # endif 88 # if ! defined(MHD_HAVE___BUILTIN_EXPECT) && __has_builtin (__builtin_expect) 89 # define MHD_HAVE___BUILTIN_EXPECT 1 90 # endif 91 # endif 92 #endif 93 94 95 /* 96 * True/false primitives with direct probability specification 97 */ 98 99 /** 100 * @def mhd_COND_PRED_TRUE_P(cond, prob) 101 * 102 * Hint that @p cond is expected to be true with probability @p prob. 103 * 104 * @param cond Boolean-like expression; evaluated exactly once. 105 * @param prob Anticipated probability in the range [0.0, 1.0]. 106 * Only compile-time constants; avoid 0.0 or 1.0. 107 * 108 * Expands to compiler-specific intrinsics when available; otherwise to 109 * a boolean normalisation of @p cond. 110 * 111 * @see mhd_COND_PRED_FALSE_P 112 */ 113 114 /** 115 * @def mhd_COND_PRED_FALSE_P(cond, prob) 116 * 117 * Hint that @p cond is expected to be false with probability @p prob. 118 * 119 * @param cond Boolean-like expression; evaluated exactly once. 120 * @param prob Anticipated probability in the range [0.0, 1.0]. 121 * Only compile-time constants; avoid 0.0 or 1.0. 122 * 123 * Expands to compiler-specific intrinsics when available; otherwise to 124 * a boolean normalisation of @p cond. 125 * 126 * @see mhd_COND_PRED_TRUE_P 127 */ 128 129 130 #if defined(MHD_HAVE___BUILTIN_EXPECT_WITH_PROBABILITY) 131 # define mhd_COND_PRED_TRUE_P(cond,prob) \ 132 __builtin_expect_with_probability (! ! (cond), ! 0, (prob)) 133 # define mhd_COND_PRED_FALSE_P(cond,prob) \ 134 __builtin_expect_with_probability (! ! (cond), 0, (prob)) 135 #elif defined(MHD_HAVE___BUILTIN_EXPECT) 136 # define mhd_COND_PRED_TRUE_P(cond,prob) __builtin_expect (! ! (cond), ! 0) 137 # define mhd_COND_PRED_FALSE_P(cond,prob) __builtin_expect (! ! (cond), 0) 138 #else 139 # define mhd_COND_PRED_TRUE_P(cond,prob) (! ! (cond)) 140 # define mhd_COND_PRED_FALSE_P(cond,prob) (! ! (cond)) 141 #endif 142 143 /* 144 * Implementation notes: 145 * - The double negation (!!) normalises any non-zero to 1 and keeps 0 as 0, 146 * ensuring the 'expected' value matches the intrinsic's contract. 147 * - The literal '!0' expresses boolean true without implying an integer 148 * width. 149 */ 150 151 152 /* 153 * Readable convenience wrappers 154 */ 155 156 /** 157 * Hint: @p cond is true ~99.999% of the time. 158 * 159 * Useful for conditions whose failure indicates exceptional or defensive 160 * paths that almost never triggered in normal operation. 161 */ 162 #define mhd_COND_VIRTUALLY_ALWAYS(cond) mhd_COND_PRED_TRUE_P ((cond), 0.99999) 163 /** 164 * Hint: @p cond is true ~99% of the time. 165 */ 166 #define mhd_COND_ALMOST_ALWAYS(cond) mhd_COND_PRED_TRUE_P ((cond), 0.99) 167 /** 168 * Hint: @p cond is true ~95% of the time. 169 */ 170 #define mhd_COND_PREDOMINANTLY(cond) mhd_COND_PRED_TRUE_P ((cond), 0.95) 171 /** 172 * Hint: @p cond is true ~90% of the time. 173 */ 174 #define mhd_COND_USUALLY(cond) mhd_COND_PRED_TRUE_P ((cond), 0.9) 175 176 /** 177 * Hint: @p cond is false ~90% of the time (i.e., the true branch is rare). 178 */ 179 #define mhd_COND_RARELY(cond) mhd_COND_PRED_FALSE_P ((cond), 0.9) 180 /** 181 * Hint: @p cond is false ~95% of the time (i.e., the true branch is very rare). 182 */ 183 #define mhd_COND_VERY_RARELY(cond) mhd_COND_PRED_FALSE_P ((cond), 0.95) 184 /** 185 * Hint: @p cond is false ~99% of the time (i.e., the true branch almost never 186 * triggers). 187 */ 188 #define mhd_COND_ALMOST_NEVER(cond) mhd_COND_PRED_FALSE_P ((cond), 0.99) 189 /** 190 * Hint: @p cond is false ~99.999% of the time. 191 * 192 * Useful for conditions whose truth indicates exceptional or defensive 193 * paths that almost never triggered in normal operation. 194 */ 195 #define mhd_COND_HARDLY_EVER(cond) mhd_COND_PRED_FALSE_P ((cond), 0.99999) 196 197 /** @} */ /* end of mhd2_predict group */ 198 199 #endif /* ! MHD_PREDICT_H */