CIRCT 21.0.0git
Loading...
Searching...
No Matches
Logging.h
Go to the documentation of this file.
1//===- Logging.h - ESI Runtime logging --------------------------*- 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// ESI runtime logging is very simple but very flexible. Rather than mandating a
10// particular logging library, it allows users to hook into their existing
11// logging system by implementing a simple interface.
12//
13//===----------------------------------------------------------------------===//
14//
15// DO NOT EDIT!
16// This file is distributed as part of an ESI package. The source for this file
17// should always be modified within CIRCT.
18//
19//===----------------------------------------------------------------------===//
20
21// NOLINTNEXTLINE(llvm-header-guard)
22#ifndef ESI_LOGGING_H
23#define ESI_LOGGING_H
24
25#include <any>
26#include <functional>
27#include <iosfwd>
28#include <map>
29#include <memory>
30#include <mutex>
31#include <string>
32
33namespace esi {
34
35class Logger {
36public:
37 enum class Level {
38 Trace, // Trace is even more detailed than debug and requires a compiler
39 // flag to be enabled when the runtime is built. Allows clients to do
40 // things like log every single message or interaction.
41 Debug, // Information useful when trying to debug an application.
42 Info, // General information, like connecting to an accelerator.
43 Warning, // May indicate a problem.
44 Error, // Many errors will be followed by exceptions which may get caught.
45 };
48 virtual ~Logger() = default;
49 bool getDebugEnabled() { return debugEnabled; }
50 bool getTraceEnabled() { return traceEnabled; }
51
52 /// Report a log message.
53 /// Arguments:
54 /// level: The log level as defined by the 'Level' enum above.
55 /// subsystem: The subsystem that generated the log message.
56 /// msg: The log message.
57 /// details: Optional additional structured details to include in the log
58 /// message. If there are no details, this should be nullptr.
59 virtual void
60 log(Level level, const std::string &subsystem, const std::string &msg,
61 const std::map<std::string, std::any> *details = nullptr) = 0;
62
63 /// Report an error.
64 virtual void error(const std::string &subsystem, const std::string &msg,
65 const std::map<std::string, std::any> *details = nullptr) {
66 log(Level::Error, subsystem, msg, details);
67 }
68 /// Report a warning.
69 virtual void
70 warning(const std::string &subsystem, const std::string &msg,
71 const std::map<std::string, std::any> *details = nullptr) {
72 log(Level::Warning, subsystem, msg, details);
73 }
74 /// Report an informational message.
75 virtual void info(const std::string &subsystem, const std::string &msg,
76 const std::map<std::string, std::any> *details = nullptr) {
77 log(Level::Info, subsystem, msg, details);
78 }
79
80 /// Report a debug message. This is not virtual so that it can be inlined to
81 /// minimize performance impact that debug messages have, allowing debug
82 /// messages in Release builds.
83 inline void debug(const std::string &subsystem, const std::string &msg,
84 const std::map<std::string, std::any> *details = nullptr) {
85 if (debugEnabled)
86 debugImpl(subsystem, msg, details);
87 }
88 /// Call the debug function callback only if debug is enabled then log a debug
89 /// message. Allows users to run heavy weight debug message generation code
90 /// only when debug is enabled, which in turns allows users to provide
91 /// fully-featured debug messages in Release builds with minimal performance
92 /// impact. Not virtual so that it can be inlined.
93 inline void
94 debug(std::function<
95 void(std::string &subsystem, std::string &msg,
96 std::unique_ptr<std::map<std::string, std::any>> &details)>
97 debugFunc) {
98 if (debugEnabled)
99 debugImpl(debugFunc);
100 }
101
102 /// Log a trace message. If tracing is not enabled, this is a no-op. Since it
103 /// is inlined, the compiler will hopefully optimize it away creating a
104 /// zero-overhead call. This means that clients are free to go crazy with
105 /// trace messages.
106 inline void trace(const std::string &subsystem, const std::string &msg,
107 const std::map<std::string, std::any> *details = nullptr) {
108#ifdef ESI_RUNTIME_TRACE
109 if (traceEnabled)
110 log(Level::Trace, subsystem, msg, details);
111#endif
112 }
113 /// Log a trace message using a callback. Same as above, users can go hog-wild
114 /// calling this.
115 inline void
116 trace(std::function<
117 void(std::string &subsystem, std::string &msg,
118 std::unique_ptr<std::map<std::string, std::any>> &details)>
119 traceFunc) {
120#ifdef ESI_RUNTIME_TRACE
121 if (!traceEnabled)
122 return;
123 std::string subsystem;
124 std::string msg;
125 std::unique_ptr<std::map<std::string, std::any>> details = nullptr;
126 traceFunc(subsystem, msg, details);
127 log(Level::Trace, subsystem, msg, details.get());
128#endif
129 }
130
131protected:
132 /// Overrideable version of debug. Only gets called if debug is enabled.
133 virtual void debugImpl(const std::string &subsystem, const std::string &msg,
134 const std::map<std::string, std::any> *details) {
135 log(Level::Debug, subsystem, msg, details);
136 }
137 /// Overrideable version of debug. Only gets called if debug is enabled.
138 virtual void
139 debugImpl(std::function<
140 void(std::string &subsystem, std::string &msg,
141 std::unique_ptr<std::map<std::string, std::any>> &details)>
142 debugFunc) {
143 if (!debugEnabled)
144 return;
145 std::string subsystem;
146 std::string msg;
147 std::unique_ptr<std::map<std::string, std::any>> details = nullptr;
148 debugFunc(subsystem, msg, details);
149 debugImpl(subsystem, msg, details.get());
150 }
151
152 /// Enable or disable debug messages.
153 bool debugEnabled = false;
154
155 /// Enable or disable trace messages.
157};
158
159/// A thread-safe logger which calls functions implemented by subclasses. Only
160/// protects the `log` method. If subclasses override other methods and need to
161/// protect them, they need to do that themselves.
162class TSLogger : public Logger {
163public:
164 using Logger::Logger;
165
166 /// Grabs the lock and calls logImpl.
167 void log(Level level, const std::string &subsystem, const std::string &msg,
168 const std::map<std::string, std::any> *details) override final;
169
170protected:
171 /// Subclasses must implement this method to log messages.
172 virtual void logImpl(Level level, const std::string &subsystem,
173 const std::string &msg,
174 const std::map<std::string, std::any> *details) = 0;
175
176 /// Mutex to protect the stream from interleaved logging writes.
177 std::mutex mutex;
178};
179
180/// A logger that writes to a C++ std::ostream.
181class StreamLogger : public TSLogger {
182public:
183 /// Create a stream logger that logs to the given output stream and error
184 /// output stream.
185 StreamLogger(Level minLevel, std::ostream &out, std::ostream &error)
188 /// Create a stream logger that logs to stdout, stderr.
190 void logImpl(Level level, const std::string &subsystem,
191 const std::string &msg,
192 const std::map<std::string, std::any> *details) override;
193
194private:
195 /// The minimum log level to emit.
197
198 /// Everything except errors goes here.
199 std::ostream &outStream;
200 /// Just for errors.
201 std::ostream &errorStream;
202};
203
204/// A logger that writes to the console. Includes color support.
205class ConsoleLogger : public TSLogger {
206public:
207 /// Create a stream logger that logs to stdout, stderr.
209 void logImpl(Level level, const std::string &subsystem,
210 const std::string &msg,
211 const std::map<std::string, std::any> *details) override;
212
213private:
214 /// The minimum log level to emit.
216};
217
218/// A logger that does nothing.
219class NullLogger : public Logger {
220public:
221 NullLogger() : Logger(false, false) {}
222 void log(Level, const std::string &, const std::string &,
223 const std::map<std::string, std::any> *) override {}
224};
225
226/// 'Stringify' a std::any. This is used to log std::any values by some loggers.
227std::string toString(const std::any &a);
228
229} // namespace esi
230
231#endif // ESI_LOGGING_H
A logger that writes to the console. Includes color support.
Definition Logging.h:205
Level minLevel
The minimum log level to emit.
Definition Logging.h:215
void logImpl(Level level, const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details) override
Subclasses must implement this method to log messages.
Definition Logging.cpp:86
bool getTraceEnabled()
Definition Logging.h:50
virtual void error(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)
Report an error.
Definition Logging.h:64
virtual void warning(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)
Report a warning.
Definition Logging.h:70
bool traceEnabled
Enable or disable trace messages.
Definition Logging.h:156
virtual void info(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)
Report an informational message.
Definition Logging.h:75
bool debugEnabled
Enable or disable debug messages.
Definition Logging.h:153
virtual void debugImpl(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details)
Overrideable version of debug. Only gets called if debug is enabled.
Definition Logging.h:133
bool getDebugEnabled()
Definition Logging.h:49
virtual ~Logger()=default
void trace(std::function< void(std::string &subsystem, std::string &msg, std::unique_ptr< std::map< std::string, std::any > > &details)> traceFunc)
Log a trace message using a callback.
Definition Logging.h:116
virtual void debugImpl(std::function< void(std::string &subsystem, std::string &msg, std::unique_ptr< std::map< std::string, std::any > > &details)> debugFunc)
Overrideable version of debug. Only gets called if debug is enabled.
Definition Logging.h:139
void debug(std::function< void(std::string &subsystem, std::string &msg, std::unique_ptr< std::map< std::string, std::any > > &details)> debugFunc)
Call the debug function callback only if debug is enabled then log a debug message.
Definition Logging.h:94
void debug(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)
Report a debug message.
Definition Logging.h:83
void trace(const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)
Log a trace message.
Definition Logging.h:106
Logger(bool debugEnabled, bool traceEnabled)
Definition Logging.h:46
virtual void log(Level level, const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details=nullptr)=0
Report a log message.
A logger that does nothing.
Definition Logging.h:219
void log(Level, const std::string &, const std::string &, const std::map< std::string, std::any > *) override
Report a log message.
Definition Logging.h:222
A logger that writes to a C++ std::ostream.
Definition Logging.h:181
Level minLevel
The minimum log level to emit.
Definition Logging.h:196
void logImpl(Level level, const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details) override
Subclasses must implement this method to log messages.
Definition Logging.cpp:37
std::ostream & outStream
Everything except errors goes here.
Definition Logging.h:199
std::ostream & errorStream
Just for errors.
Definition Logging.h:201
StreamLogger(Level minLevel, std::ostream &out, std::ostream &error)
Create a stream logger that logs to the given output stream and error output stream.
Definition Logging.h:185
A thread-safe logger which calls functions implemented by subclasses.
Definition Logging.h:162
std::mutex mutex
Mutex to protect the stream from interleaved logging writes.
Definition Logging.h:177
virtual void logImpl(Level level, const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details)=0
Subclasses must implement this method to log messages.
void log(Level level, const std::string &subsystem, const std::string &msg, const std::map< std::string, std::any > *details) override final
Grabs the lock and calls logImpl.
Definition Logging.cpp:26
Definition esi.py:1
std::string toString(const std::any &a)
'Stringify' a std::any. This is used to log std::any values by some loggers.
Definition Logging.cpp:132