log_severity.h (7074B)
1 // Copyright 2017 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef ABSL_BASE_LOG_SEVERITY_H_ 16 #define ABSL_BASE_LOG_SEVERITY_H_ 17 18 #include <array> 19 #include <ostream> 20 21 #include "absl/base/attributes.h" 22 #include "absl/base/config.h" 23 24 namespace absl { 25 ABSL_NAMESPACE_BEGIN 26 27 // absl::LogSeverity 28 // 29 // Four severity levels are defined. Logging APIs should terminate the program 30 // when a message is logged at severity `kFatal`; the other levels have no 31 // special semantics. 32 // 33 // Values other than the four defined levels (e.g. produced by `static_cast`) 34 // are valid, but their semantics when passed to a function, macro, or flag 35 // depend on the function, macro, or flag. The usual behavior is to normalize 36 // such values to a defined severity level, however in some cases values other 37 // than the defined levels are useful for comparison. 38 // 39 // Example: 40 // 41 // // Effectively disables all logging: 42 // SetMinLogLevel(static_cast<absl::LogSeverity>(100)); 43 // 44 // Abseil flags may be defined with type `LogSeverity`. Dependency layering 45 // constraints require that the `AbslParseFlag()` overload be declared and 46 // defined in the flags library itself rather than here. The `AbslUnparseFlag()` 47 // overload is defined there as well for consistency. 48 // 49 // absl::LogSeverity Flag String Representation 50 // 51 // An `absl::LogSeverity` has a string representation used for parsing 52 // command-line flags based on the enumerator name (e.g. `kFatal`) or 53 // its unprefixed name (without the `k`) in any case-insensitive form. (E.g. 54 // "FATAL", "fatal" or "Fatal" are all valid.) Unparsing such flags produces an 55 // unprefixed string representation in all caps (e.g. "FATAL") or an integer. 56 // 57 // Additionally, the parser accepts arbitrary integers (as if the type were 58 // `int`). 59 // 60 // Examples: 61 // 62 // --my_log_level=kInfo 63 // --my_log_level=INFO 64 // --my_log_level=info 65 // --my_log_level=0 66 // 67 // `DFATAL` and `kLogDebugFatal` are similarly accepted. 68 // 69 // Unparsing a flag produces the same result as `absl::LogSeverityName()` for 70 // the standard levels and a base-ten integer otherwise. 71 enum class LogSeverity : int { 72 kInfo = 0, 73 kWarning = 1, 74 kError = 2, 75 kFatal = 3, 76 }; 77 78 // LogSeverities() 79 // 80 // Returns an iterable of all standard `absl::LogSeverity` values, ordered from 81 // least to most severe. 82 constexpr std::array<absl::LogSeverity, 4> LogSeverities() { 83 return {{absl::LogSeverity::kInfo, absl::LogSeverity::kWarning, 84 absl::LogSeverity::kError, absl::LogSeverity::kFatal}}; 85 } 86 87 // `absl::kLogDebugFatal` equals `absl::LogSeverity::kFatal` in debug builds 88 // (i.e. when `NDEBUG` is not defined) and `absl::LogSeverity::kError` 89 // otherwise. Avoid ODR-using this variable as it has internal linkage and thus 90 // distinct storage in different TUs. 91 #ifdef NDEBUG 92 static constexpr absl::LogSeverity kLogDebugFatal = absl::LogSeverity::kError; 93 #else 94 static constexpr absl::LogSeverity kLogDebugFatal = absl::LogSeverity::kFatal; 95 #endif 96 97 // LogSeverityName() 98 // 99 // Returns the all-caps string representation (e.g. "INFO") of the specified 100 // severity level if it is one of the standard levels and "UNKNOWN" otherwise. 101 constexpr const char* LogSeverityName(absl::LogSeverity s) { 102 switch (s) { 103 case absl::LogSeverity::kInfo: return "INFO"; 104 case absl::LogSeverity::kWarning: return "WARNING"; 105 case absl::LogSeverity::kError: return "ERROR"; 106 case absl::LogSeverity::kFatal: return "FATAL"; 107 } 108 return "UNKNOWN"; 109 } 110 111 // NormalizeLogSeverity() 112 // 113 // Values less than `kInfo` normalize to `kInfo`; values greater than `kFatal` 114 // normalize to `kError` (**NOT** `kFatal`). 115 constexpr absl::LogSeverity NormalizeLogSeverity(absl::LogSeverity s) { 116 absl::LogSeverity n = s; 117 if (n < absl::LogSeverity::kInfo) n = absl::LogSeverity::kInfo; 118 if (n > absl::LogSeverity::kFatal) n = absl::LogSeverity::kError; 119 return n; 120 } 121 constexpr absl::LogSeverity NormalizeLogSeverity(int s) { 122 return absl::NormalizeLogSeverity(static_cast<absl::LogSeverity>(s)); 123 } 124 125 // operator<< 126 // 127 // The exact representation of a streamed `absl::LogSeverity` is deliberately 128 // unspecified; do not rely on it. 129 std::ostream& operator<<(std::ostream& os, absl::LogSeverity s); 130 131 // Enums representing a lower bound for LogSeverity. APIs that only operate on 132 // messages of at least a certain level (for example, `SetMinLogLevel()`) use 133 // this type to specify that level. absl::LogSeverityAtLeast::kInfinity is 134 // a level above all threshold levels and therefore no log message will 135 // ever meet this threshold. 136 enum class LogSeverityAtLeast : int { 137 kInfo = static_cast<int>(absl::LogSeverity::kInfo), 138 kWarning = static_cast<int>(absl::LogSeverity::kWarning), 139 kError = static_cast<int>(absl::LogSeverity::kError), 140 kFatal = static_cast<int>(absl::LogSeverity::kFatal), 141 kInfinity = 1000, 142 }; 143 144 std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtLeast s); 145 146 // Enums representing an upper bound for LogSeverity. APIs that only operate on 147 // messages of at most a certain level (for example, buffer all messages at or 148 // below a certain level) use this type to specify that level. 149 // absl::LogSeverityAtMost::kNegativeInfinity is a level below all threshold 150 // levels and therefore will exclude all log messages. 151 enum class LogSeverityAtMost : int { 152 kNegativeInfinity = -1000, 153 kInfo = static_cast<int>(absl::LogSeverity::kInfo), 154 kWarning = static_cast<int>(absl::LogSeverity::kWarning), 155 kError = static_cast<int>(absl::LogSeverity::kError), 156 kFatal = static_cast<int>(absl::LogSeverity::kFatal), 157 }; 158 159 std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtMost s); 160 161 #define COMPOP(op1, op2, T) \ 162 constexpr bool operator op1(absl::T lhs, absl::LogSeverity rhs) { \ 163 return static_cast<absl::LogSeverity>(lhs) op1 rhs; \ 164 } \ 165 constexpr bool operator op2(absl::LogSeverity lhs, absl::T rhs) { \ 166 return lhs op2 static_cast<absl::LogSeverity>(rhs); \ 167 } 168 169 // Comparisons between `LogSeverity` and `LogSeverityAtLeast`/ 170 // `LogSeverityAtMost` are only supported in one direction. 171 // Valid checks are: 172 // LogSeverity >= LogSeverityAtLeast 173 // LogSeverity < LogSeverityAtLeast 174 // LogSeverity <= LogSeverityAtMost 175 // LogSeverity > LogSeverityAtMost 176 COMPOP(>, <, LogSeverityAtLeast) 177 COMPOP(<=, >=, LogSeverityAtLeast) 178 COMPOP(<, >, LogSeverityAtMost) 179 COMPOP(>=, <=, LogSeverityAtMost) 180 #undef COMPOP 181 182 ABSL_NAMESPACE_END 183 } // namespace absl 184 185 #endif // ABSL_BASE_LOG_SEVERITY_H_