LLDB mainline
Log.h
Go to the documentation of this file.
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
32namespace llvm {
33class 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
46namespace lldb_private {
47
49public:
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
56private:
57 static char ID;
58};
59
61public:
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
71private:
72 std::mutex m_mutex;
73 llvm::raw_fd_ostream m_stream;
74 static char ID;
75};
76
78public:
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
86private:
88 void *m_baton;
89 static char ID;
90};
91
93public:
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
102private:
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/// A T-style log handler that multiplexes messages to two log handlers.
116class TeeLogHandler : public LogHandler {
117public:
118 TeeLogHandler(std::shared_ptr<LogHandler> first_log_handler,
119 std::shared_ptr<LogHandler> second_log_handler);
120
121 void Emit(llvm::StringRef message) override;
122
123 bool isA(const void *ClassID) const override { return ClassID == &ID; }
124 static bool classof(const LogHandler *obj) { return obj->isA(&ID); }
125
126private:
127 std::shared_ptr<LogHandler> m_first_log_handler;
128 std::shared_ptr<LogHandler> m_second_log_handler;
129 static char ID;
130};
131
132class Log final {
133public:
134 /// The underlying type of all log channel enums. Declare them as:
135 /// enum class MyLog : MaskType {
136 /// Channel0 = Log::ChannelFlag<0>,
137 /// Channel1 = Log::ChannelFlag<1>,
138 /// ...,
139 /// LLVM_MARK_AS_BITMASK_ENUM(LastChannel),
140 /// };
141 using MaskType = uint64_t;
142
143 template <MaskType Bit>
144 static constexpr MaskType ChannelFlag = MaskType(1) << Bit;
145
146 // Description of a log channel category.
147 struct Category {
148 llvm::StringLiteral name;
149 llvm::StringLiteral description;
151
152 template <typename Cat>
153 constexpr Category(llvm::StringLiteral name,
154 llvm::StringLiteral description, Cat mask)
156 static_assert(
157 std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value);
158 }
159 };
160
161 // This class describes a log channel. It also encapsulates the behavior
162 // necessary to enable a log channel in an atomic manner.
163 class Channel {
164 std::atomic<Log *> log_ptr;
165 friend class Log;
166
167 public:
168 const llvm::ArrayRef<Category> categories;
170
171 template <typename Cat>
172 constexpr Channel(llvm::ArrayRef<Log::Category> categories,
173 Cat default_flags)
174 : log_ptr(nullptr), categories(categories),
176 static_assert(
177 std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value);
178 }
179
180 // This function is safe to call at any time. If the channel is disabled
181 // after (or concurrently with) this function returning a non-null Log
182 // pointer, it is still safe to attempt to write to the Log object -- the
183 // output will be discarded.
185 Log *log = log_ptr.load(std::memory_order_relaxed);
186 if (log && ((log->GetMask() & mask) != 0))
187 return log;
188 return nullptr;
189 }
190 };
191
192
193 // Static accessors for logging channels
194 static void Register(llvm::StringRef name, Channel &channel);
195 static void Unregister(llvm::StringRef name);
196
197 static bool
198 EnableLogChannel(const std::shared_ptr<LogHandler> &log_handler_sp,
199 uint32_t log_options, llvm::StringRef channel,
200 llvm::ArrayRef<const char *> categories,
201 llvm::raw_ostream &error_stream);
202
203 static bool DisableLogChannel(llvm::StringRef channel,
204 llvm::ArrayRef<const char *> categories,
205 llvm::raw_ostream &error_stream);
206
207 static bool DumpLogChannel(llvm::StringRef channel,
208 llvm::raw_ostream &output_stream,
209 llvm::raw_ostream &error_stream);
210
211 static bool ListChannelCategories(llvm::StringRef channel,
212 llvm::raw_ostream &stream);
213
214 /// Returns the list of log channels.
215 static std::vector<llvm::StringRef> ListChannels();
216 /// Calls the given lambda for every category in the given channel.
217 /// If no channel with the given name exists, lambda is never called.
218 static void ForEachChannelCategory(
219 llvm::StringRef channel,
220 llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda);
221
222 static void DisableAllLogChannels();
223
224 static void ListAllLogChannels(llvm::raw_ostream &stream);
225
226 // Member functions
227 //
228 // These functions are safe to call at any time you have a Log* obtained from
229 // the Channel class. If logging is disabled between you obtaining the Log
230 // object and writing to it, the output will be silently discarded.
231 Log(Channel &channel) : m_channel(channel) {}
232 ~Log() = default;
233
234 void PutCString(const char *cstr);
235 void PutString(llvm::StringRef str);
236
237 template <typename... Args>
238 void Format(llvm::StringRef file, llvm::StringRef function,
239 const char *format, Args &&... args) {
240 Format(file, function, llvm::formatv(format, std::forward<Args>(args)...));
241 }
242
243 template <typename... Args>
244 void FormatError(llvm::Error error, llvm::StringRef file,
245 llvm::StringRef function, const char *format,
246 Args &&... args) {
247 Format(file, function,
248 llvm::formatv(format, llvm::toString(std::move(error)),
249 std::forward<Args>(args)...));
250 }
251
252 void Formatf(llvm::StringRef file, llvm::StringRef function,
253 const char *format, ...) __attribute__((format(printf, 4, 5)));
254
255 /// Prefer using LLDB_LOGF whenever possible.
256 void Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
257
258 void Error(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
259
260 void Verbose(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
261
262 void Warning(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
263
264 const Flags GetOptions() const;
265
266 MaskType GetMask() const;
267
268 bool GetVerbose() const;
269
270 void VAPrintf(const char *format, va_list args);
271 void VAError(const char *format, va_list args);
272 void VAFormatf(llvm::StringRef file, llvm::StringRef function,
273 const char *format, va_list args);
274
275private:
277
278 // The mutex makes sure enable/disable operations are thread-safe. The
279 // options and mask variables are atomic to enable their reading in
280 // Channel::GetLogIfAny without taking the mutex to speed up the fast path.
281 // Their modification however, is still protected by this mutex.
282 llvm::sys::RWMutex m_mutex;
283
284 std::shared_ptr<LogHandler> m_handler;
285 std::atomic<uint32_t> m_options{0};
286 std::atomic<MaskType> m_mask{0};
287
288 void WriteHeader(llvm::raw_ostream &OS, llvm::StringRef file,
289 llvm::StringRef function);
290 void WriteMessage(llvm::StringRef message);
291
292 void Format(llvm::StringRef file, llvm::StringRef function,
293 const llvm::formatv_object_base &payload);
294
295 std::shared_ptr<LogHandler> GetHandler() {
296 llvm::sys::ScopedReader lock(m_mutex);
297 return m_handler;
298 }
299
300 void Enable(const std::shared_ptr<LogHandler> &handler_sp, uint32_t options,
301 MaskType flags);
302
303 void Disable(MaskType flags);
304
305 bool Dump(llvm::raw_ostream &stream);
306
307 typedef llvm::StringMap<Log> ChannelMap;
308 static llvm::ManagedStatic<ChannelMap> g_channel_map;
309
310 static void ForEachCategory(
311 const Log::ChannelMap::value_type &entry,
312 llvm::function_ref<void(llvm::StringRef, llvm::StringRef)> lambda);
313
314 static void ListCategories(llvm::raw_ostream &stream,
315 const ChannelMap::value_type &entry);
316 static Log::MaskType GetFlags(llvm::raw_ostream &stream,
317 const ChannelMap::value_type &entry,
318 llvm::ArrayRef<const char *> categories);
319
320 Log(const Log &) = delete;
321 void operator=(const Log &) = delete;
322};
323
324// Must be specialized for a particular log type.
325template <typename Cat> Log::Channel &LogChannelFor() = delete;
326
327/// Retrieve the Log object for the channel associated with the given log enum.
328///
329/// Returns a valid Log object if any of the provided categories are enabled.
330/// Otherwise, returns nullptr.
331template <typename Cat> Log *GetLog(Cat mask) {
332 static_assert(
333 std::is_same<Log::MaskType, std::underlying_type_t<Cat>>::value);
334 return LogChannelFor<Cat>().GetLog(Log::MaskType(mask));
335}
336
337} // namespace lldb_private
338
339/// The LLDB_LOG* macros defined below are the way to emit log messages.
340///
341/// Note that the macros surround the arguments in a check for the log
342/// being on, so you can freely call methods in arguments without affecting
343/// the non-log execution flow.
344///
345/// If you need to do more complex computations to prepare the log message
346/// be sure to add your own if (log) check, since we don't want logging to
347/// have any effect when not on.
348///
349/// However, the LLDB_LOG macro uses the llvm::formatv system (see the
350/// ProgrammersManual page in the llvm docs for more details). This allows
351/// the use of "format_providers" to auto-format datatypes, and there are
352/// already formatters for some of the llvm and lldb datatypes.
353///
354/// So if you need to do non-trivial formatting of one of these types, be
355/// sure to grep the lldb and llvm sources for "format_provider" to see if
356/// there is already a formatter before doing in situ formatting, and if
357/// possible add a provider if one does not already exist.
358
359#define LLDB_LOG(log, ...) \
360 do { \
361 ::lldb_private::Log *log_private = (log); \
362 if (log_private) \
363 log_private->Format(__FILE__, __func__, __VA_ARGS__); \
364 } while (0)
365
366#define LLDB_LOGF(log, ...) \
367 do { \
368 ::lldb_private::Log *log_private = (log); \
369 if (log_private) \
370 log_private->Formatf(__FILE__, __func__, __VA_ARGS__); \
371 } while (0)
372
373#define LLDB_LOGV(log, ...) \
374 do { \
375 ::lldb_private::Log *log_private = (log); \
376 if (log_private && log_private->GetVerbose()) \
377 log_private->Format(__FILE__, __func__, __VA_ARGS__); \
378 } while (0)
379
380// Write message to log, if error is set. In the log message refer to the error
381// with {0}. Error is cleared regardless of whether logging is enabled.
382#define LLDB_LOG_ERROR(log, error, ...) \
383 do { \
384 ::lldb_private::Log *log_private = (log); \
385 ::llvm::Error error_private = (error); \
386 if (log_private && error_private) { \
387 log_private->FormatError(::std::move(error_private), __FILE__, __func__, \
388 __VA_ARGS__); \
389 } else \
390 ::llvm::consumeError(::std::move(error_private)); \
391 } while (0)
392
393// Write message to the verbose log, if error is set. In the log
394// message refer to the error with {0}. Error is cleared regardless of
395// whether logging is enabled.
396#define LLDB_LOG_ERRORV(log, error, ...) \
397 do { \
398 ::lldb_private::Log *log_private = (log); \
399 ::llvm::Error error_private = (error); \
400 if (log_private && log_private->GetVerbose() && error_private) { \
401 log_private->FormatError(::std::move(error_private), __FILE__, __func__, \
402 __VA_ARGS__); \
403 } else \
404 ::llvm::consumeError(::std::move(error_private)); \
405 } while (0)
406
407#endif // LLDB_UTILITY_LOG_H
static llvm::raw_ostream & error(Stream &strm)
llvm::Error Error
A command line argument class.
Definition: Args.h:33
lldb::LogOutputCallback m_callback
Definition: Log.h:87
static bool classof(const LogHandler *obj)
Definition: Log.h:84
bool isA(const void *ClassID) const override
Definition: Log.h:83
void Emit(llvm::StringRef message) override
Definition: Log.cpp:407
A class to manage flags.
Definition: Flags.h:22
virtual void Emit(llvm::StringRef message)=0
virtual bool isA(const void *ClassID) const
Definition: Log.h:53
static bool classof(const LogHandler *obj)
Definition: Log.h:54
static char ID
Definition: Log.h:57
virtual ~LogHandler()=default
constexpr Channel(llvm::ArrayRef< Log::Category > categories, Cat default_flags)
Definition: Log.h:172
Log * GetLog(MaskType mask)
Definition: Log.h:184
const llvm::ArrayRef< Category > categories
Definition: Log.h:168
std::atomic< Log * > log_ptr
Definition: Log.h:164
const MaskType default_flags
Definition: Log.h:169
llvm::sys::RWMutex m_mutex
Definition: Log.h:282
static void ListCategories(llvm::raw_ostream &stream, const ChannelMap::value_type &entry)
Definition: Log.cpp:55
void Disable(MaskType flags)
Definition: Log.cpp:107
std::shared_ptr< LogHandler > m_handler
Definition: Log.h:284
void WriteMessage(llvm::StringRef message)
Definition: Log.cpp:362
void PutCString(const char *cstr)
Definition: Log.cpp:135
static void ForEachCategory(const Log::ChannelMap::value_type &entry, llvm::function_ref< void(llvm::StringRef, llvm::StringRef)> lambda)
Definition: Log.cpp:46
static constexpr MaskType ChannelFlag
Definition: Log.h:144
llvm::StringMap< Log > ChannelMap
Definition: Log.h:307
void Formatf(llvm::StringRef file, llvm::StringRef function, const char *format,...) __attribute__((format(printf
Definition: Log.cpp:159
uint64_t MaskType
The underlying type of all log channel enums.
Definition: Log.h:141
Log(const Log &)=delete
static bool DisableLogChannel(llvm::StringRef channel, llvm::ArrayRef< const char * > categories, llvm::raw_ostream &error_stream)
Definition: Log.cpp:240
static void Register(llvm::StringRef name, Channel &channel)
Definition: Log.cpp:211
static void ListAllLogChannels(llvm::raw_ostream &stream)
Definition: Log.cpp:304
void VAFormatf(llvm::StringRef file, llvm::StringRef function, const char *format, va_list args)
Definition: Log.cpp:167
void WriteHeader(llvm::raw_ostream &OS, llvm::StringRef file, llvm::StringRef function)
Definition: Log.cpp:318
static bool DumpLogChannel(llvm::StringRef channel, llvm::raw_ostream &output_stream, llvm::raw_ostream &error_stream)
Definition: Log.cpp:255
void VAPrintf(const char *format, va_list args)
Definition: Log.cpp:153
void FormatError(llvm::Error error, llvm::StringRef file, llvm::StringRef function, const char *format, Args &&... args)
Definition: Log.h:244
void Format(llvm::StringRef file, llvm::StringRef function, const char *format, Args &&... args)
Definition: Log.h:238
static llvm::ManagedStatic< ChannelMap > g_channel_map
Definition: Log.h:308
std::shared_ptr< LogHandler > GetHandler()
Definition: Log.h:295
Log(Channel &channel)
Definition: Log.h:231
void void void void void Warning(const char *fmt,...) __attribute__((format(printf
Definition: Log.cpp:201
std::atomic< MaskType > m_mask
Definition: Log.h:286
static void Unregister(llvm::StringRef name)
Definition: Log.cpp:217
static bool ListChannelCategories(llvm::StringRef channel, llvm::raw_ostream &stream)
Definition: Log.cpp:271
static void DisableAllLogChannels()
Definition: Log.cpp:282
static void ForEachChannelCategory(llvm::StringRef channel, llvm::function_ref< void(llvm::StringRef, llvm::StringRef)> lambda)
Calls the given lambda for every category in the given channel.
Definition: Log.cpp:287
void void void void void const Flags GetOptions() const
Definition: Log.cpp:127
static bool EnableLogChannel(const std::shared_ptr< LogHandler > &log_handler_sp, uint32_t log_options, llvm::StringRef channel, llvm::ArrayRef< const char * > categories, llvm::raw_ostream &error_stream)
Definition: Log.cpp:224
void operator=(const Log &)=delete
MaskType GetMask() const
Definition: Log.cpp:131
void VAError(const char *format, va_list args)
Definition: Log.cpp:182
static std::vector< llvm::StringRef > ListChannels()
Returns the list of log channels.
Definition: Log.cpp:297
void Enable(const std::shared_ptr< LogHandler > &handler_sp, uint32_t options, MaskType flags)
Definition: Log.cpp:95
static Log::MaskType GetFlags(llvm::raw_ostream &stream, const ChannelMap::value_type &entry, llvm::ArrayRef< const char * > categories)
Definition: Log.cpp:64
bool GetVerbose() const
Definition: Log.cpp:314
void PutString(llvm::StringRef str)
Definition: Log.cpp:137
bool Dump(llvm::raw_ostream &stream)
Definition: Log.cpp:117
void void Printf(const char *format,...) __attribute__((format(printf
Prefer using LLDB_LOGF whenever possible.
Definition: Log.cpp:146
void void void void Verbose(const char *fmt,...) __attribute__((format(printf
Definition: Log.cpp:190
std::atomic< uint32_t > m_options
Definition: Log.h:285
Channel & m_channel
Definition: Log.h:276
void Dump(llvm::raw_ostream &stream) const
Definition: Log.cpp:432
std::unique_ptr< std::string[]> m_messages
Definition: Log.h:108
bool isA(const void *ClassID) const override
Definition: Log.h:99
void Emit(llvm::StringRef message) override
Definition: Log.cpp:414
static bool classof(const LogHandler *obj)
Definition: Log.h:100
size_t NormalizeIndex(size_t i) const
Definition: Log.cpp:422
size_t GetNumMessages() const
Definition: Log.cpp:424
size_t GetFirstMessageIndex() const
Definition: Log.cpp:428
~StreamLogHandler() override
Definition: Log.cpp:387
llvm::raw_fd_ostream m_stream
Definition: Log.h:73
void Emit(llvm::StringRef message) override
Definition: Log.cpp:394
bool isA(const void *ClassID) const override
Definition: Log.h:68
static bool classof(const LogHandler *obj)
Definition: Log.h:69
A T-style log handler that multiplexes messages to two log handlers.
Definition: Log.h:116
void Emit(llvm::StringRef message) override
Definition: Log.cpp:451
std::shared_ptr< LogHandler > m_first_log_handler
Definition: Log.h:127
bool isA(const void *ClassID) const override
Definition: Log.h:123
static bool classof(const LogHandler *obj)
Definition: Log.h:124
std::shared_ptr< LogHandler > m_second_log_handler
Definition: Log.h:128
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
Log * GetLog(Cat mask)
Retrieve the Log object for the channel associated with the given log enum.
Definition: Log.h:331
Log::Channel & LogChannelFor()=delete
void(* LogOutputCallback)(const char *, void *baton)
Definition: lldb-types.h:73
Definition: Debugger.h:54
llvm::StringLiteral name
Definition: Log.h:148
llvm::StringLiteral description
Definition: Log.h:149
constexpr Category(llvm::StringLiteral name, llvm::StringLiteral description, Cat mask)
Definition: Log.h:153