contrib/llvm/tools/lldb/include/lldb/Utility/Log.h

   1 //===-- Log.h ---------------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_UTILITY_LOG_H
  11 #define LLDB_UTILITY_LOG_H
  12
  13 #include "lldb/Utility/Flags.h"
  14 #include "lldb/Utility/Logging.h"
  15 #include "lldb/lldb-defines.h"
  16
  17 #include "llvm/ADT/ArrayRef.h"
  18 #include "llvm/ADT/StringMap.h" // for StringMap
  19 #include "llvm/ADT/StringRef.h" // for StringRef, StringLiteral
  20 #include "llvm/Support/Error.h"
  21 #include "llvm/Support/FormatVariadic.h"
  22 #include "llvm/Support/ManagedStatic.h"
  23 #include "llvm/Support/RWMutex.h"
  24
  25 #include <atomic>
  26 #include <cstdarg>
  27 #include <cstdint>
  28 #include <memory>      // for shared_ptr
  29 #include <string>      // for string
  30 #include <type_traits> // for forward
  31
  32 namespace llvm {
  33 class raw_ostream;
  34 }
  35 //----------------------------------------------------------------------
  36 // Logging Options
  37 //----------------------------------------------------------------------
  38 #define LLDB_LOG_OPTION_THREADSAFE (1u << 0)
  39 #define LLDB_LOG_OPTION_VERBOSE (1u << 1)
  40 #define LLDB_LOG_OPTION_PREPEND_SEQUENCE (1u << 3)
  41 #define LLDB_LOG_OPTION_PREPEND_TIMESTAMP (1u << 4)
  42 #define LLDB_LOG_OPTION_PREPEND_PROC_AND_THREAD (1u << 5)
  43 #define LLDB_LOG_OPTION_PREPEND_THREAD_NAME (1U << 6)
  44 #define LLDB_LOG_OPTION_BACKTRACE (1U << 7)
  45 #define LLDB_LOG_OPTION_APPEND (1U << 8)
  46 #define LLDB_LOG_OPTION_PREPEND_FILE_FUNCTION (1U << 9)
  47
  48 //----------------------------------------------------------------------
  49 // Logging Functions
  50 //----------------------------------------------------------------------
  51 namespace lldb_private {
  52
  53 class Log final {
  54 public:
  55   // Description of a log channel category.
  56   struct Category {
  57     llvm::StringLiteral name;
  58     llvm::StringLiteral description;
  59     uint32_t flag;
  60   };
  61
  62   // This class describes a log channel. It also encapsulates the behavior
  63   // necessary to enable a log channel in an atomic manner.
  64   class Channel {
  65     std::atomic<Log *> log_ptr;
  66     friend class Log;
  67
  68   public:
  69     const llvm::ArrayRef<Category> categories;
  70     const uint32_t default_flags;
  71
  72     constexpr Channel(llvm::ArrayRef<Log::Category> categories,
  73                       uint32_t default_flags)
  74         : log_ptr(nullptr), categories(categories),
  75           default_flags(default_flags) {}
  76
  77     // This function is safe to call at any time If the channel is disabled
  78     // after (or concurrently with) this function returning a non-null Log
  79     // pointer, it is still safe to attempt to write to the Log object -- the
  80     // output will be discarded.
  81     Log *GetLogIfAll(uint32_t mask) {
  82       Log *log = log_ptr.load(std::memory_order_relaxed);
  83       if (log && log->GetMask().AllSet(mask))
  84         return log;
  85       return nullptr;
  86     }
  87
  88     // This function is safe to call at any time If the channel is disabled
  89     // after (or concurrently with) this function returning a non-null Log
  90     // pointer, it is still safe to attempt to write to the Log object -- the
  91     // output will be discarded.
  92     Log *GetLogIfAny(uint32_t mask) {
  93       Log *log = log_ptr.load(std::memory_order_relaxed);
  94       if (log && log->GetMask().AnySet(mask))
  95         return log;
  96       return nullptr;
  97     }
  98   };
  99
 100
 101   static void Initialize();
 102
 103   //------------------------------------------------------------------
 104   // Static accessors for logging channels
 105   //------------------------------------------------------------------
 106   static void Register(llvm::StringRef name, Channel &channel);
 107   static void Unregister(llvm::StringRef name);
 108
 109   static bool
 110   EnableLogChannel(const std::shared_ptr<llvm::raw_ostream> &log_stream_sp,
 111                    uint32_t log_options, llvm::StringRef channel,
 112                    llvm::ArrayRef<const char *> categories,
 113                    llvm::raw_ostream &error_stream);
 114
 115   static bool DisableLogChannel(llvm::StringRef channel,
 116                                 llvm::ArrayRef<const char *> categories,
 117                                 llvm::raw_ostream &error_stream);
 118
 119   static bool ListChannelCategories(llvm::StringRef channel, llvm::raw_ostream &stream);
 120
 121   static void DisableAllLogChannels();
 122
 123   static void ListAllLogChannels(llvm::raw_ostream &stream);
 124
 125   //------------------------------------------------------------------
 126   // Member functions
 127   //
 128   // These functions are safe to call at any time you have a Log* obtained from
 129   // the Channel class. If logging is disabled between you obtaining the Log
 130   // object and writing to it, the output will be silently discarded.
 131   //------------------------------------------------------------------
 132   Log(Channel &channel) : m_channel(channel) {}
 133   ~Log() = default;
 134
 135   void PutCString(const char *cstr);
 136   void PutString(llvm::StringRef str);
 137
 138   template <typename... Args>
 139   void Format(llvm::StringRef file, llvm::StringRef function,
 140               const char *format, Args &&... args) {
 141     Format(file, function, llvm::formatv(format, std::forward<Args>(args)...));
 142   }
 143
 144   template <typename... Args>
 145   void FormatError(llvm::Error error, llvm::StringRef file,
 146                    llvm::StringRef function, const char *format,
 147                    Args &&... args) {
 148     Format(file, function,
 149            llvm::formatv(format, llvm::toString(std::move(error)),
 150                          std::forward<Args>(args)...));
 151   }
 152
 153   void Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
 154
 155   void VAPrintf(const char *format, va_list args);
 156
 157   void Error(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 158
 159   void VAError(const char *format, va_list args);
 160
 161   void Verbose(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 162
 163   void Warning(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 164
 165   const Flags GetOptions() const;
 166
 167   const Flags GetMask() const;
 168
 169   bool GetVerbose() const;
 170
 171 private:
 172   Channel &m_channel;
 173
 174   // The mutex makes sure enable/disable operations are thread-safe. The
 175   // options and mask variables are atomic to enable their reading in
 176   // Channel::GetLogIfAny without taking the mutex to speed up the fast path.
 177   // Their modification however, is still protected by this mutex.
 178   llvm::sys::RWMutex m_mutex;
 179
 180   std::shared_ptr<llvm::raw_ostream> m_stream_sp;
 181   std::atomic<uint32_t> m_options{0};
 182   std::atomic<uint32_t> m_mask{0};
 183
 184   void WriteHeader(llvm::raw_ostream &OS, llvm::StringRef file,
 185                    llvm::StringRef function);
 186   void WriteMessage(const std::string &message);
 187
 188   void Format(llvm::StringRef file, llvm::StringRef function,
 189               const llvm::formatv_object_base &payload);
 190
 191   std::shared_ptr<llvm::raw_ostream> GetStream() {
 192     llvm::sys::ScopedReader lock(m_mutex);
 193     return m_stream_sp;
 194   }
 195
 196   void Enable(const std::shared_ptr<llvm::raw_ostream> &stream_sp,
 197               uint32_t options, uint32_t flags);
 198
 199   void Disable(uint32_t flags);
 200
 201   typedef llvm::StringMap<Log> ChannelMap;
 202   static llvm::ManagedStatic<ChannelMap> g_channel_map;
 203
 204   static void ListCategories(llvm::raw_ostream &stream,
 205                              const ChannelMap::value_type &entry);
 206   static uint32_t GetFlags(llvm::raw_ostream &stream, const ChannelMap::value_type &entry,
 207                            llvm::ArrayRef<const char *> categories);
 208
 209   static void DisableLoggingChild();
 210
 211   Log(const Log &) = delete;
 212   void operator=(const Log &) = delete;
 213 };
 214
 215 } // namespace lldb_private
 216
 217 #define LLDB_LOG(log, ...)                                                     \
 218   do {                                                                         \
 219     ::lldb_private::Log *log_private = (log);                                  \
 220     if (log_private)                                                           \
 221       log_private->Format(__FILE__, __func__, __VA_ARGS__);                    \
 222   } while (0)
 223
 224 #define LLDB_LOGV(log, ...)                                                    \
 225   do {                                                                         \
 226     ::lldb_private::Log *log_private = (log);                                  \
 227     if (log_private && log_private->GetVerbose())                              \
 228       log_private->Format(__FILE__, __func__, __VA_ARGS__);                    \
 229   } while (0)
 230
 231 // Write message to log, if error is set. In the log message refer to the error
 232 // with {0}. Error is cleared regardless of whether logging is enabled.
 233 #define LLDB_LOG_ERROR(log, error, ...)                                        \
 234   do {                                                                         \
 235     ::lldb_private::Log *log_private = (log);                                  \
 236     ::llvm::Error error_private = (error);                                     \
 237     if (log_private && error_private) {                                        \
 238       log_private->FormatError(::std::move(error_private), __FILE__, __func__, \
 239                                __VA_ARGS__);                                   \
 240     } else                                                                     \
 241       ::llvm::consumeError(::std::move(error_private));                        \
 242   } while (0)
 243
 244 #endif // LLDB_UTILITY_LOG_H