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
isA(const void * ClassID)53 virtual bool isA(const void *ClassID) const { return ClassID == &ID; }
classof(const LogHandler * obj)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
isA(const void * ClassID)68 bool isA(const void *ClassID) const override { return ClassID == &ID; }
classof(const LogHandler * obj)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
isA(const void * ClassID)83 bool isA(const void *ClassID) const override { return ClassID == &ID; }
classof(const LogHandler * obj)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
isA(const void * ClassID)99 bool isA(const void *ClassID) const override { return ClassID == &ID; }
classof(const LogHandler * obj)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>
CategoryCategory136 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>
Channel(llvm::ArrayRef<Log::Category> categories,Cat default_flags)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.
GetLog(MaskType mask)167 Log *GetLog(MaskType mask) {
168 Log *log = log_ptr.load(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.
Log(Channel & channel)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>
Format(llvm::StringRef file,llvm::StringRef function,const char * format,Args &&...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>
FormatError(llvm::Error error,llvm::StringRef file,llvm::StringRef function,const char * format,Args &&...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 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 WriteHeader(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
GetHandler()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.
GetLog(Cat mask)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