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(ClassID: &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(ClassID: &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(ClassID: &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(ClassID: &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(m: std::memory_order_relaxed); |
169 | if (log && ((log->GetMask() & mask) != 0)) |
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(E: std::move(error)), |
232 | std::forward<Args>(args)...)); |
233 | } |
234 | |
235 | void Formatf(llvm::StringRef file, llvm::StringRef function, |
236 | const char *format, ...) __attribute__((format(printf, 4, 5))); |
237 | |
238 | /// Prefer using LLDB_LOGF whenever possible. |
239 | void Printf(const char *format, ...) __attribute__((format(printf, 2, 3))); |
240 | |
241 | void Error(const char *fmt, ...) __attribute__((format(printf, 2, 3))); |
242 | |
243 | void Verbose(const char *fmt, ...) __attribute__((format(printf, 2, 3))); |
244 | |
245 | void Warning(const char *fmt, ...) __attribute__((format(printf, 2, 3))); |
246 | |
247 | const Flags GetOptions() const; |
248 | |
249 | MaskType GetMask() const; |
250 | |
251 | bool GetVerbose() const; |
252 | |
253 | void VAPrintf(const char *format, va_list args); |
254 | void VAError(const char *format, va_list args); |
255 | void VAFormatf(llvm::StringRef file, llvm::StringRef function, |
256 | const char *format, va_list args); |
257 | |
258 | private: |
259 | Channel &m_channel; |
260 | |
261 | // The mutex makes sure enable/disable operations are thread-safe. The |
262 | // options and mask variables are atomic to enable their reading in |
263 | // Channel::GetLogIfAny without taking the mutex to speed up the fast path. |
264 | // Their modification however, is still protected by this mutex. |
265 | llvm::sys::RWMutex m_mutex; |
266 | |
267 | std::shared_ptr<LogHandler> m_handler; |
268 | std::atomic<uint32_t> m_options{0}; |
269 | std::atomic<MaskType> m_mask{0}; |
270 | |
271 | void (llvm::raw_ostream &OS, llvm::StringRef file, |
272 | llvm::StringRef function); |
273 | void WriteMessage(llvm::StringRef message); |
274 | |
275 | void Format(llvm::StringRef file, llvm::StringRef function, |
276 | const llvm::formatv_object_base &payload); |
277 | |
278 | std::shared_ptr<LogHandler> GetHandler() { |
279 | llvm::sys::ScopedReader lock(m_mutex); |
280 | return m_handler; |
281 | } |
282 | |
283 | void Enable(const std::shared_ptr<LogHandler> &handler_sp, uint32_t options, |
284 | MaskType flags); |
285 | |
286 | void Disable(MaskType flags); |
287 | |
288 | bool Dump(llvm::raw_ostream &stream); |
289 | |
290 | typedef llvm::StringMap<Log> ChannelMap; |
291 | static llvm::ManagedStatic<ChannelMap> g_channel_map; |
292 | |
293 | static void ForEachCategory( |
294 | const Log::ChannelMap::value_type &entry, |
295 | llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda); |
296 | |
297 | static void ListCategories(llvm::raw_ostream &stream, |
298 | const ChannelMap::value_type &entry); |
299 | static Log::MaskType GetFlags(llvm::raw_ostream &stream, |
300 | const ChannelMap::value_type &entry, |
301 | llvm::ArrayRef<const char *> categories); |
302 | |
303 | Log(const Log &) = delete; |
304 | void operator=(const Log &) = delete; |
305 | }; |
306 | |
307 | // Must be specialized for a particular log type. |
308 | template <typename Cat> Log::Channel &LogChannelFor() = delete; |
309 | |
310 | /// Retrieve the Log object for the channel associated with the given log enum. |
311 | /// |
312 | /// Returns a valid Log object if any of the provided categories are enabled. |
313 | /// Otherwise, returns nullptr. |
314 | template <typename Cat> Log *GetLog(Cat mask) { |
315 | static_assert( |
316 | std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value); |
317 | return LogChannelFor<Cat>().GetLog(Log::MaskType(mask)); |
318 | } |
319 | |
320 | } // namespace lldb_private |
321 | |
322 | /// The LLDB_LOG* macros defined below are the way to emit log messages. |
323 | /// |
324 | /// Note that the macros surround the arguments in a check for the log |
325 | /// being on, so you can freely call methods in arguments without affecting |
326 | /// the non-log execution flow. |
327 | /// |
328 | /// If you need to do more complex computations to prepare the log message |
329 | /// be sure to add your own if (log) check, since we don't want logging to |
330 | /// have any effect when not on. |
331 | /// |
332 | /// However, the LLDB_LOG macro uses the llvm::formatv system (see the |
333 | /// ProgrammersManual page in the llvm docs for more details). This allows |
334 | /// the use of "format_providers" to auto-format datatypes, and there are |
335 | /// already formatters for some of the llvm and lldb datatypes. |
336 | /// |
337 | /// So if you need to do non-trivial formatting of one of these types, be |
338 | /// sure to grep the lldb and llvm sources for "format_provider" to see if |
339 | /// there is already a formatter before doing in situ formatting, and if |
340 | /// possible add a provider if one does not already exist. |
341 | |
342 | #define LLDB_LOG(log, ...) \ |
343 | do { \ |
344 | ::lldb_private::Log *log_private = (log); \ |
345 | if (log_private) \ |
346 | log_private->Format(__FILE__, __func__, __VA_ARGS__); \ |
347 | } while (0) |
348 | |
349 | #define LLDB_LOGF(log, ...) \ |
350 | do { \ |
351 | ::lldb_private::Log *log_private = (log); \ |
352 | if (log_private) \ |
353 | log_private->Formatf(__FILE__, __func__, __VA_ARGS__); \ |
354 | } while (0) |
355 | |
356 | #define LLDB_LOGV(log, ...) \ |
357 | do { \ |
358 | ::lldb_private::Log *log_private = (log); \ |
359 | if (log_private && log_private->GetVerbose()) \ |
360 | log_private->Format(__FILE__, __func__, __VA_ARGS__); \ |
361 | } while (0) |
362 | |
363 | // Write message to log, if error is set. In the log message refer to the error |
364 | // with {0}. Error is cleared regardless of whether logging is enabled. |
365 | #define LLDB_LOG_ERROR(log, error, ...) \ |
366 | do { \ |
367 | ::lldb_private::Log *log_private = (log); \ |
368 | ::llvm::Error error_private = (error); \ |
369 | if (log_private && error_private) { \ |
370 | log_private->FormatError(::std::move(error_private), __FILE__, __func__, \ |
371 | __VA_ARGS__); \ |
372 | } else \ |
373 | ::llvm::consumeError(::std::move(error_private)); \ |
374 | } while (0) |
375 | |
376 | #endif // LLDB_UTILITY_LOG_H |
377 | |