clang-tools  13.0.0git
Logger.h
Go to the documentation of this file.
1 //===--- Logger.h - Logger interface for clangd ------------------*- 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 LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_LOGGER_H
10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_LOGGER_H
11 
12 #include "llvm/ADT/Twine.h"
13 #include "llvm/Support/Debug.h"
14 #include "llvm/Support/Error.h"
15 #include "llvm/Support/FormatAdapters.h"
16 #include "llvm/Support/FormatVariadic.h"
17 #include <mutex>
18 
19 namespace clang {
20 namespace clangd {
21 
22 /// Interface to allow custom logging in clangd.
23 class Logger {
24 public:
25  virtual ~Logger() = default;
26 
27  /// The significance or severity of this message.
28  /// Typically used to filter the output to an interesting level.
29  enum Level : unsigned char { Debug, Verbose, Info, Error };
30  static char indicator(Level L) { return "DVIE"[L]; }
31 
32  /// Implementations of this method must be thread-safe.
33  virtual void log(Level, const char *Fmt,
34  const llvm::formatv_object_base &Message) = 0;
35 };
36 
37 namespace detail {
38 const char *debugType(const char *Filename);
39 void logImpl(Logger::Level, const char *Fmt, const llvm::formatv_object_base &);
40 
41 // We often want to consume llvm::Errors by value when passing them to log().
42 // We automatically wrap them in llvm::fmt_consume() as formatv requires.
43 template <typename T> T &&wrap(T &&V) { return std::forward<T>(V); }
44 inline decltype(fmt_consume(llvm::Error::success())) wrap(llvm::Error &&V) {
45  return fmt_consume(std::move(V));
46 }
47 template <typename... Ts>
48 void log(Logger::Level L, const char *Fmt, Ts &&... Vals) {
49  detail::logImpl(L, Fmt,
50  llvm::formatv(Fmt, detail::wrap(std::forward<Ts>(Vals))...));
51 }
52 
53 llvm::Error error(std::error_code, std::string &&);
54 } // namespace detail
55 
56 // Clangd logging functions write to a global logger set by LoggingSession.
57 // If no logger is registered, writes to llvm::errs().
58 // All accept llvm::formatv()-style arguments, e.g. log("Text={0}", Text).
59 
60 // elog() is used for "loud" errors and warnings.
61 // This level is often visible to users.
62 template <typename... Ts> void elog(const char *Fmt, Ts &&... Vals) {
63  detail::log(Logger::Error, Fmt, std::forward<Ts>(Vals)...);
64 }
65 // log() is used for information important to understand a clangd session.
66 // e.g. the names of LSP messages sent are logged at this level.
67 // This level could be enabled in production builds to allow later inspection.
68 template <typename... Ts> void log(const char *Fmt, Ts &&... Vals) {
69  detail::log(Logger::Info, Fmt, std::forward<Ts>(Vals)...);
70 }
71 // vlog() is used for details often needed for debugging clangd sessions.
72 // This level would typically be enabled for clangd developers.
73 template <typename... Ts> void vlog(const char *Fmt, Ts &&... Vals) {
74  detail::log(Logger::Verbose, Fmt, std::forward<Ts>(Vals)...);
75 }
76 // error() constructs an llvm::Error object, using formatv()-style arguments.
77 // It is not automatically logged! (This function is a little out of place).
78 // The error simply embeds the message string.
79 template <typename... Ts>
80 llvm::Error error(std::error_code EC, const char *Fmt, Ts &&... Vals) {
81  // We must render the formatv_object eagerly, while references are valid.
82  return detail::error(
83  EC, llvm::formatv(Fmt, detail::wrap(std::forward<Ts>(Vals))...).str());
84 }
85 // Overload with no error_code conversion, the error will be inconvertible.
86 template <typename... Ts> llvm::Error error(const char *Fmt, Ts &&... Vals) {
87  return detail::error(
88  llvm::inconvertibleErrorCode(),
89  llvm::formatv(Fmt, detail::wrap(std::forward<Ts>(Vals))...).str());
90 }
91 // Overload to avoid formatv complexity for simple strings.
92 inline llvm::Error error(std::error_code EC, std::string Msg) {
93  return detail::error(EC, std::move(Msg));
94 }
95 // Overload for simple strings with no error_code conversion.
96 inline llvm::Error error(std::string Msg) {
97  return detail::error(llvm::inconvertibleErrorCode(), std::move(Msg));
98 }
99 
100 // dlog only logs if --debug was passed, or --debug_only=Basename.
101 // This level would be enabled in a targeted way when debugging.
102 #define dlog(...) \
103  DEBUG_WITH_TYPE(::clang::clangd::detail::debugType(__FILE__), \
104  ::clang::clangd::detail::log(Logger::Debug, __VA_ARGS__))
105 
106 /// Only one LoggingSession can be active at a time.
108 public:
109  LoggingSession(clangd::Logger &Instance);
110  ~LoggingSession();
111 
112  LoggingSession(LoggingSession &&) = delete;
114 
115  LoggingSession(LoggingSession const &) = delete;
116  LoggingSession &operator=(LoggingSession const &) = delete;
117 };
118 
119 // Logs to an output stream, such as stderr.
120 class StreamLogger : public Logger {
121 public:
122  StreamLogger(llvm::raw_ostream &Logs, Logger::Level MinLevel)
123  : MinLevel(MinLevel), Logs(Logs) {}
124 
125  /// Write a line to the logging stream.
126  void log(Level, const char *Fmt,
127  const llvm::formatv_object_base &Message) override;
128 
129 private:
130  Logger::Level MinLevel;
131  llvm::raw_ostream &Logs;
132 
133  std::mutex StreamMutex;
134 };
135 
136 } // namespace clangd
137 } // namespace clang
138 
139 #endif
clang::clangd::detail::logImpl
void logImpl(Logger::Level, const char *Fmt, const llvm::formatv_object_base &)
Definition: Logger.cpp:31
clang::clangd::Logger::Debug
@ Debug
Definition: Logger.h:29
llvm
Some operations such as code completion produce a set of candidates.
Definition: YAMLGenerator.cpp:28
clang::clangd::Logger::Info
@ Info
Definition: Logger.h:29
clang::clangd::Logger::Verbose
@ Verbose
Definition: Logger.h:29
clang::clangd::error
llvm::Error error(std::error_code EC, const char *Fmt, Ts &&... Vals)
Definition: Logger.h:80
clang::clangd::Logger
Interface to allow custom logging in clangd.
Definition: Logger.h:23
clang::clangd::StreamLogger
Definition: Logger.h:120
clang::clangd::detail::error
llvm::Error error(std::error_code, std::string &&)
Definition: Logger.cpp:80
clang::tidy::bugprone::Message
static const char Message[]
Definition: ReservedIdentifierCheck.cpp:31
Filename
std::string Filename
Filename as a string.
Definition: IncludeOrderCheck.cpp:39
clang::clangd::LoggingSession::~LoggingSession
~LoggingSession()
Definition: Logger.cpp:29
clang::clangd::detail::debugType
const char * debugType(const char *Filename)
Definition: Logger.cpp:42
clang::clangd::Logger::Level
Level
The significance or severity of this message.
Definition: Logger.h:29
clang::clangd::Logger::~Logger
virtual ~Logger()=default
clang::clangd::Logger::log
virtual void log(Level, const char *Fmt, const llvm::formatv_object_base &Message)=0
Implementations of this method must be thread-safe.
clang::clangd::StreamLogger::StreamLogger
StreamLogger(llvm::raw_ostream &Logs, Logger::Level MinLevel)
Definition: Logger.h:122
clang::clangd::LoggingSession::operator=
LoggingSession & operator=(LoggingSession &&)=delete
clang::clangd::LoggingSession
Only one LoggingSession can be active at a time.
Definition: Logger.h:107
clang::clangd::vlog
void vlog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:73
clang::clangd::log
void log(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:68
clang::clangd::Logger::Error
@ Error
Definition: Logger.h:29
clang::clangd::StreamLogger::log
void log(Level, const char *Fmt, const llvm::formatv_object_base &Message) override
Write a line to the logging stream.
Definition: Logger.cpp:50
clang::clangd::detail::wrap
T && wrap(T &&V)
Definition: Logger.h:43
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::Logger::indicator
static char indicator(Level L)
Definition: Logger.h:30
clang::clangd::LoggingSession::LoggingSession
LoggingSession(clangd::Logger &Instance)
Definition: Logger.cpp:24
clang::clangd::elog
void elog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:62
clang::clangd::detail::log
void log(Logger::Level L, const char *Fmt, Ts &&... Vals)
Definition: Logger.h:48