1 //===-- Log.h ---------------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_UTILITY_LOG_H 10 #define LLDB_UTILITY_LOG_H 11 12 #include "lldb/Utility/Flags.h" 13 #include "lldb/lldb-defines.h" 14 15 #include "llvm/ADT/ArrayRef.h" 16 #include "llvm/ADT/STLExtras.h" 17 #include "llvm/ADT/StringMap.h" 18 #include "llvm/ADT/StringRef.h" 19 #include "llvm/Support/Error.h" 20 #include "llvm/Support/FormatVariadic.h" 21 #include "llvm/Support/ManagedStatic.h" 22 #include "llvm/Support/RWMutex.h" 23 24 #include <atomic> 25 #include <cstdarg> 26 #include <cstdint> 27 #include <memory> 28 #include <mutex> 29 #include <string> 30 #include <type_traits> 31 32 namespace llvm { 33 class raw_ostream; 34 } 35 // Logging Options 36 #define LLDB_LOG_OPTION_VERBOSE (1u << 1) 37 #define LLDB_LOG_OPTION_PREPEND_SEQUENCE (1u << 3) 38 #define LLDB_LOG_OPTION_PREPEND_TIMESTAMP (1u << 4) 39 #define LLDB_LOG_OPTION_PREPEND_PROC_AND_THREAD (1u << 5) 40 #define LLDB_LOG_OPTION_PREPEND_THREAD_NAME (1U << 6) 41 #define LLDB_LOG_OPTION_BACKTRACE (1U << 7) 42 #define LLDB_LOG_OPTION_APPEND (1U << 8) 43 #define LLDB_LOG_OPTION_PREPEND_FILE_FUNCTION (1U << 9) 44 45 // Logging Functions 46 namespace lldb_private { 47 48 class LogHandler { 49 public: 50 virtual ~LogHandler() = default; 51 virtual void Emit(llvm::StringRef message) = 0; 52 53 virtual bool isA(const void *ClassID) const { return ClassID == &ID; } 54 static bool classof(const LogHandler *obj) { return obj->isA(&ID); } 55 56 private: 57 static char ID; 58 }; 59 60 class StreamLogHandler : public LogHandler { 61 public: 62 StreamLogHandler(int fd, bool should_close, size_t buffer_size = 0); 63 ~StreamLogHandler() override; 64 65 void Emit(llvm::StringRef message) override; 66 void Flush(); 67 68 bool isA(const void *ClassID) const override { return ClassID == &ID; } 69 static bool classof(const LogHandler *obj) { return obj->isA(&ID); } 70 71 private: 72 std::mutex m_mutex; 73 llvm::raw_fd_ostream m_stream; 74 static char ID; 75 }; 76 77 class CallbackLogHandler : public LogHandler { 78 public: 79 CallbackLogHandler(lldb::LogOutputCallback callback, void *baton); 80 81 void Emit(llvm::StringRef message) override; 82 83 bool isA(const void *ClassID) const override { return ClassID == &ID; } 84 static bool classof(const LogHandler *obj) { return obj->isA(&ID); } 85 86 private: 87 lldb::LogOutputCallback m_callback; 88 void *m_baton; 89 static char ID; 90 }; 91 92 class RotatingLogHandler : public LogHandler { 93 public: 94 RotatingLogHandler(size_t size); 95 96 void Emit(llvm::StringRef message) override; 97 void Dump(llvm::raw_ostream &stream) const; 98 99 bool isA(const void *ClassID) const override { return ClassID == &ID; } 100 static bool classof(const LogHandler *obj) { return obj->isA(&ID); } 101 102 private: 103 size_t NormalizeIndex(size_t i) const; 104 size_t GetNumMessages() const; 105 size_t GetFirstMessageIndex() const; 106 107 mutable std::mutex m_mutex; 108 std::unique_ptr<std::string[]> m_messages; 109 const size_t m_size = 0; 110 size_t m_next_index = 0; 111 size_t m_total_count = 0; 112 static char ID; 113 }; 114 115 class Log final { 116 public: 117 /// The underlying type of all log channel enums. Declare them as: 118 /// enum class MyLog : MaskType { 119 /// Channel0 = Log::ChannelFlag<0>, 120 /// Channel1 = Log::ChannelFlag<1>, 121 /// ..., 122 /// LLVM_MARK_AS_BITMASK_ENUM(LastChannel), 123 /// }; 124 using MaskType = uint64_t; 125 126 template <MaskType Bit> 127 static constexpr MaskType ChannelFlag = MaskType(1) << Bit; 128 129 // Description of a log channel category. 130 struct Category { 131 llvm::StringLiteral name; 132 llvm::StringLiteral description; 133 MaskType flag; 134 135 template <typename Cat> 136 constexpr Category(llvm::StringLiteral name, 137 llvm::StringLiteral description, Cat mask) 138 : name(name), description(description), flag(MaskType(mask)) { 139 static_assert( 140 std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value, ""); 141 } 142 }; 143 144 // This class describes a log channel. It also encapsulates the behavior 145 // necessary to enable a log channel in an atomic manner. 146 class Channel { 147 std::atomic<Log *> log_ptr; 148 friend class Log; 149 150 public: 151 const llvm::ArrayRef<Category> categories; 152 const MaskType default_flags; 153 154 template <typename Cat> 155 constexpr Channel(llvm::ArrayRef<Log::Category> categories, 156 Cat default_flags) 157 : log_ptr(nullptr), categories(categories), 158 default_flags(MaskType(default_flags)) { 159 static_assert( 160 std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value, ""); 161 } 162 163 // This function is safe to call at any time. If the channel is disabled 164 // after (or concurrently with) this function returning a non-null Log 165 // pointer, it is still safe to attempt to write to the Log object -- the 166 // output will be discarded. 167 Log *GetLog(MaskType mask) { 168 Log *log = log_ptr.load(std::memory_order_relaxed); 169 if (log && log->GetMask().AnySet(mask)) 170 return log; 171 return nullptr; 172 } 173 }; 174 175 176 // Static accessors for logging channels 177 static void Register(llvm::StringRef name, Channel &channel); 178 static void Unregister(llvm::StringRef name); 179 180 static bool 181 EnableLogChannel(const std::shared_ptr<LogHandler> &log_handler_sp, 182 uint32_t log_options, llvm::StringRef channel, 183 llvm::ArrayRef<const char *> categories, 184 llvm::raw_ostream &error_stream); 185 186 static bool DisableLogChannel(llvm::StringRef channel, 187 llvm::ArrayRef<const char *> categories, 188 llvm::raw_ostream &error_stream); 189 190 static bool DumpLogChannel(llvm::StringRef channel, 191 llvm::raw_ostream &output_stream, 192 llvm::raw_ostream &error_stream); 193 194 static bool ListChannelCategories(llvm::StringRef channel, 195 llvm::raw_ostream &stream); 196 197 /// Returns the list of log channels. 198 static std::vector<llvm::StringRef> ListChannels(); 199 /// Calls the given lambda for every category in the given channel. 200 /// If no channel with the given name exists, lambda is never called. 201 static void ForEachChannelCategory( 202 llvm::StringRef channel, 203 llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda); 204 205 static void DisableAllLogChannels(); 206 207 static void ListAllLogChannels(llvm::raw_ostream &stream); 208 209 // Member functions 210 // 211 // These functions are safe to call at any time you have a Log* obtained from 212 // the Channel class. If logging is disabled between you obtaining the Log 213 // object and writing to it, the output will be silently discarded. 214 Log(Channel &channel) : m_channel(channel) {} 215 ~Log() = default; 216 217 void PutCString(const char *cstr); 218 void PutString(llvm::StringRef str); 219 220 template <typename... Args> 221 void Format(llvm::StringRef file, llvm::StringRef function, 222 const char *format, Args &&... args) { 223 Format(file, function, llvm::formatv(format, std::forward<Args>(args)...)); 224 } 225 226 template <typename... Args> 227 void FormatError(llvm::Error error, llvm::StringRef file, 228 llvm::StringRef function, const char *format, 229 Args &&... args) { 230 Format(file, function, 231 llvm::formatv(format, llvm::toString(std::move(error)), 232 std::forward<Args>(args)...)); 233 } 234 235 /// Prefer using LLDB_LOGF whenever possible. 236 void Printf(const char *format, ...) __attribute__((format(printf, 2, 3))); 237 238 void Error(const char *fmt, ...) __attribute__((format(printf, 2, 3))); 239 240 void Verbose(const char *fmt, ...) __attribute__((format(printf, 2, 3))); 241 242 void Warning(const char *fmt, ...) __attribute__((format(printf, 2, 3))); 243 244 const Flags GetOptions() const; 245 246 const Flags GetMask() const; 247 248 bool GetVerbose() const; 249 250 void VAPrintf(const char *format, va_list args); 251 void VAError(const char *format, va_list args); 252 253 private: 254 Channel &m_channel; 255 256 // The mutex makes sure enable/disable operations are thread-safe. The 257 // options and mask variables are atomic to enable their reading in 258 // Channel::GetLogIfAny without taking the mutex to speed up the fast path. 259 // Their modification however, is still protected by this mutex. 260 llvm::sys::RWMutex m_mutex; 261 262 std::shared_ptr<LogHandler> m_handler; 263 std::atomic<uint32_t> m_options{0}; 264 std::atomic<MaskType> m_mask{0}; 265 266 void WriteHeader(llvm::raw_ostream &OS, llvm::StringRef file, 267 llvm::StringRef function); 268 void WriteMessage(const std::string &message); 269 270 void Format(llvm::StringRef file, llvm::StringRef function, 271 const llvm::formatv_object_base &payload); 272 273 std::shared_ptr<LogHandler> GetHandler() { 274 llvm::sys::ScopedReader lock(m_mutex); 275 return m_handler; 276 } 277 278 void Enable(const std::shared_ptr<LogHandler> &handler_sp, uint32_t options, 279 uint32_t flags); 280 281 void Disable(uint32_t flags); 282 283 bool Dump(llvm::raw_ostream &stream); 284 285 typedef llvm::StringMap<Log> ChannelMap; 286 static llvm::ManagedStatic<ChannelMap> g_channel_map; 287 288 static void ForEachCategory( 289 const Log::ChannelMap::value_type &entry, 290 llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda); 291 292 static void ListCategories(llvm::raw_ostream &stream, 293 const ChannelMap::value_type &entry); 294 static uint32_t GetFlags(llvm::raw_ostream &stream, const ChannelMap::value_type &entry, 295 llvm::ArrayRef<const char *> categories); 296 297 Log(const Log &) = delete; 298 void operator=(const Log &) = delete; 299 }; 300 301 // Must be specialized for a particular log type. 302 template <typename Cat> Log::Channel &LogChannelFor() = delete; 303 304 /// Retrieve the Log object for the channel associated with the given log enum. 305 /// 306 /// Returns a valid Log object if any of the provided categories are enabled. 307 /// Otherwise, returns nullptr. 308 template <typename Cat> Log *GetLog(Cat mask) { 309 static_assert(std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value, 310 ""); 311 return LogChannelFor<Cat>().GetLog(Log::MaskType(mask)); 312 } 313 314 } // namespace lldb_private 315 316 /// The LLDB_LOG* macros defined below are the way to emit log messages. 317 /// 318 /// Note that the macros surround the arguments in a check for the log 319 /// being on, so you can freely call methods in arguments without affecting 320 /// the non-log execution flow. 321 /// 322 /// If you need to do more complex computations to prepare the log message 323 /// be sure to add your own if (log) check, since we don't want logging to 324 /// have any effect when not on. 325 /// 326 /// However, the LLDB_LOG macro uses the llvm::formatv system (see the 327 /// ProgrammersManual page in the llvm docs for more details). This allows 328 /// the use of "format_providers" to auto-format datatypes, and there are 329 /// already formatters for some of the llvm and lldb datatypes. 330 /// 331 /// So if you need to do non-trivial formatting of one of these types, be 332 /// sure to grep the lldb and llvm sources for "format_provider" to see if 333 /// there is already a formatter before doing in situ formatting, and if 334 /// possible add a provider if one does not already exist. 335 336 #define LLDB_LOG(log, ...) \ 337 do { \ 338 ::lldb_private::Log *log_private = (log); \ 339 if (log_private) \ 340 log_private->Format(__FILE__, __func__, __VA_ARGS__); \ 341 } while (0) 342 343 #define LLDB_LOGF(log, ...) \ 344 do { \ 345 ::lldb_private::Log *log_private = (log); \ 346 if (log_private) \ 347 log_private->Printf(__VA_ARGS__); \ 348 } while (0) 349 350 #define LLDB_LOGV(log, ...) \ 351 do { \ 352 ::lldb_private::Log *log_private = (log); \ 353 if (log_private && log_private->GetVerbose()) \ 354 log_private->Format(__FILE__, __func__, __VA_ARGS__); \ 355 } while (0) 356 357 // Write message to log, if error is set. In the log message refer to the error 358 // with {0}. Error is cleared regardless of whether logging is enabled. 359 #define LLDB_LOG_ERROR(log, error, ...) \ 360 do { \ 361 ::lldb_private::Log *log_private = (log); \ 362 ::llvm::Error error_private = (error); \ 363 if (log_private && error_private) { \ 364 log_private->FormatError(::std::move(error_private), __FILE__, __func__, \ 365 __VA_ARGS__); \ 366 } else \ 367 ::llvm::consumeError(::std::move(error_private)); \ 368 } while (0) 369 370 #endif // LLDB_UTILITY_LOG_H 371 372 // TODO: Remove this and fix includes everywhere. 373