GCC Middle and Back End API Reference
analyzer-logging.h
Go to the documentation of this file.
1/* Hierarchical log messages for the analyzer.
2 Copyright (C) 2014-2026 Free Software Foundation, Inc.
3 Contributed by David Malcolm <dmalcolm@redhat.com>.
4
5This file is part of GCC.
6
7GCC is free software; you can redistribute it and/or modify it
8under the terms of the GNU General Public License as published by
9the Free Software Foundation; either version 3, or (at your option)
10any later version.
11
12GCC is distributed in the hope that it will be useful, but
13WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with GCC; see the file COPYING3. If not see
19<http://www.gnu.org/licenses/>. */
20
21/* Adapted from jit-logging.h. */
22
23#ifndef ANALYZER_LOGGING_H
24#define ANALYZER_LOGGING_H
25
26#include "diagnostic-core.h"
27
28namespace text_art { class canvas; }
29
30namespace ana {
31
32/* A logger encapsulates a logging stream: a way to send
33 lines of pertinent information to a FILE *. */
34
35class logger
36{
37 public:
38 logger (FILE *f_out, int flags, int verbosity, const pretty_printer &reference_pp);
40
41 void incref (const char *reason);
42 void decref (const char *reason);
43
44 void log (const char *fmt, ...)
46 void log_va (const char *fmt, va_list *ap)
49 void log_partial (const char *fmt, ...)
51 void log_va_partial (const char *fmt, va_list *ap)
53 void end_log_line ();
54
55 void log_canvas (const text_art::canvas &);
56
57 const text_art::theme *
59 {
60 return m_text_art_theme.get ();
61 }
62
63 void enter_scope (const char *scope_name);
64 void enter_scope (const char *scope_name, const char *fmt, va_list *ap)
66 void exit_scope (const char *scope_name);
69
70 pretty_printer *get_printer () const { return m_pp.get (); }
71 FILE *get_file () const { return m_f_out; }
72
73private:
75
77 FILE *m_f_out;
80 std::unique_ptr<pretty_printer> m_pp;
81 std::unique_ptr<text_art::theme> m_text_art_theme;
82};
83
84/* The class log_scope is an RAII-style class intended to make
85 it easy to notify a logger about entering and exiting the body of a
86 given function. */
87
89{
90public:
91 log_scope (logger *logger, const char *name);
92 log_scope (logger *logger, const char *name, const char *fmt, ...)
94 ~log_scope ();
95
96 private:
98
100 const char *m_name;
101};
102
103/* The constructor for log_scope.
104
105 The normal case is that the logger is nullptr, in which case this should
106 be largely a no-op.
107
108 If we do have a logger, notify it that we're entering the given scope.
109 We also need to hold a reference on it, to avoid a use-after-free
110 when logging the cleanup of the owner of the logger. */
111
112inline
113log_scope::log_scope (logger *logger, const char *name) :
115 m_name (name)
116{
117 if (m_logger)
118 {
119 m_logger->incref ("log_scope ctor");
121 }
122}
123
124inline
125log_scope::log_scope (logger *logger, const char *name, const char *fmt, ...):
127 m_name (name)
128{
129 if (m_logger)
130 {
131 m_logger->incref ("log_scope ctor");
132 va_list ap;
133 va_start (ap, fmt);
134 m_logger->enter_scope (m_name, fmt, &ap);
135 va_end (ap);
136 }
137}
138
139
140/* The destructor for log_scope; essentially the opposite of
141 the constructor. */
142
143inline
145{
146 if (m_logger)
147 {
149 m_logger->decref ("log_scope dtor");
150 }
151}
152
154{
155public:
156 log_nesting_level (logger *logger, const char *fmt, ...)
157 ATTRIBUTE_GCC_DIAG(3, 4);
159
160private:
162};
163
164inline
167{
168 if (logger)
169 {
170 va_list ap;
171 va_start (ap, fmt);
172
174 logger->log_va_partial (fmt, &ap);
176
177 logger->inc_indent ();
178
179 va_end (ap);
180 }
181}
182
183
184/* The destructor for log_nesting_level; essentially the opposite of
185 the constructor. */
186
187inline
193
194/* A log_user is something that potentially uses a logger (which could be
195 nullptr).
196
197 The log_user class keeps the reference-count of a logger up-to-date. */
198
200{
201 public:
204
205 logger * get_logger () const { return m_logger; }
207
208 void log (const char *fmt, ...) const
209 ATTRIBUTE_GCC_DIAG(2, 3);
210
211 void start_log_line () const;
212 void end_log_line () const;
213
214 void enter_scope (const char *scope_name);
215 void exit_scope (const char *scope_name);
216
218 {
220 return m_logger->get_printer ();
221 }
222
223 FILE *get_logger_file () const
224 {
225 if (m_logger == nullptr)
226 return nullptr;
227 return m_logger->get_file ();
228 }
229
230 private:
232
234};
235
236/* A shortcut for calling log from a log_user, handling the common
237 case where the underlying logger is nullptr via a no-op. */
238
239inline void
240log_user::log (const char *fmt, ...) const
241{
242 if (m_logger)
243 {
244 va_list ap;
245 va_start (ap, fmt);
246 m_logger->log_va (fmt, &ap);
247 va_end (ap);
248 }
249}
250
251/* A shortcut for starting a log line from a log_user,
252 handling the common case where the underlying logger is nullptr via
253 a no-op. */
254
255inline void
257{
258 if (m_logger)
260}
261
262/* A shortcut for ending a log line from a log_user,
263 handling the common case where the underlying logger is nullptr via
264 a no-op. */
265
266inline void
268{
269 if (m_logger)
271}
272
273/* A shortcut for recording entry into a scope from a log_user,
274 handling the common case where the underlying logger is nullptr via
275 a no-op. */
276
277inline void
278log_user::enter_scope (const char *scope_name)
279{
280 if (m_logger)
281 m_logger->enter_scope (scope_name);
282}
283
284/* A shortcut for recording exit from a scope from a log_user,
285 handling the common case where the underlying logger is nullptr via
286 a no-op. */
287
288inline void
289log_user::exit_scope (const char *scope_name)
290{
291 if (m_logger)
292 m_logger->exit_scope (scope_name);
293}
294
295/* If the given logger is non-NULL, log entry/exit of this scope to
296 it, identifying it using __PRETTY_FUNCTION__. */
297
298#define LOG_SCOPE(LOGGER) \
299 log_scope s (LOGGER, __PRETTY_FUNCTION__)
300
301/* If the given logger is non-NULL, log entry/exit of this scope to
302 it, identifying it using __func__. */
303
304#define LOG_FUNC(LOGGER) \
305 log_scope s (LOGGER, __func__)
306
307#define LOG_FUNC_1(LOGGER, FMT, A0) \
308 log_scope s (LOGGER, __func__, FMT, A0)
309
310#define LOG_FUNC_2(LOGGER, FMT, A0, A1) \
311 log_scope s (LOGGER, __func__, FMT, A0, A1)
312
313#define LOG_FUNC_3(LOGGER, FMT, A0, A1, A2) \
314 log_scope s (LOGGER, __func__, FMT, A0, A1, A2)
315
316#define LOG_FUNC_4(LOGGER, FMT, A0, A1, A2, A3) \
317 log_scope s (LOGGER, __func__, FMT, A0, A1, A2, A3)
318
319} // namespace ana
320
321#endif /* ANALYZER_LOGGING_H */
log_nesting_level(logger *logger, const char *fmt,...) ATTRIBUTE_GCC_DIAG(3
Definition analyzer-logging.h:165
logger * m_logger
Definition analyzer-logging.h:161
~log_nesting_level()
Definition analyzer-logging.h:188
const char * m_name
Definition analyzer-logging.h:100
logger * m_logger
Definition analyzer-logging.h:99
~log_scope()
Definition analyzer-logging.h:144
DISABLE_COPY_AND_ASSIGN(log_scope)
log_scope(logger *logger, const char *name)
Definition analyzer-logging.h:113
DISABLE_COPY_AND_ASSIGN(log_user)
logger * get_logger() const
Definition analyzer-logging.h:205
logger * m_logger
Definition analyzer-logging.h:233
void log(const char *fmt,...) const ATTRIBUTE_GCC_DIAG(2
Definition analyzer-logging.h:240
void enter_scope(const char *scope_name)
Definition analyzer-logging.h:278
void void start_log_line() const
Definition analyzer-logging.h:256
log_user(logger *logger)
void set_logger(logger *logger)
void exit_scope(const char *scope_name)
Definition analyzer-logging.h:289
FILE * get_logger_file() const
Definition analyzer-logging.h:223
void end_log_line() const
Definition analyzer-logging.h:267
pretty_printer * get_logger_pp() const
Definition analyzer-logging.h:217
Definition analyzer-logging.h:36
void dec_indent()
Definition analyzer-logging.h:68
int m_indent_level
Definition analyzer-logging.h:78
pretty_printer * get_printer() const
Definition analyzer-logging.h:70
void void log_va_partial(const char *fmt, va_list *ap) ATTRIBUTE_GCC_DIAG(2
void log_partial(const char *fmt,...) ATTRIBUTE_GCC_DIAG(2
void log(const char *fmt,...) ATTRIBUTE_GCC_DIAG(2
DISABLE_COPY_AND_ASSIGN(logger)
FILE * get_file() const
Definition analyzer-logging.h:71
void enter_scope(const char *scope_name)
bool m_log_refcount_changes
Definition analyzer-logging.h:79
FILE * m_f_out
Definition analyzer-logging.h:77
int m_refcount
Definition analyzer-logging.h:76
void void void start_log_line()
logger(FILE *f_out, int flags, int verbosity, const pretty_printer &reference_pp)
std::unique_ptr< text_art::theme > m_text_art_theme
Definition analyzer-logging.h:81
void incref(const char *reason)
void void log_va(const char *fmt, va_list *ap) ATTRIBUTE_GCC_DIAG(2
void log_canvas(const text_art::canvas &)
void inc_indent()
Definition analyzer-logging.h:67
void enter_scope(const char *scope_name, const char *fmt, va_list *ap) ATTRIBUTE_GCC_DIAG(3
void decref(const char *reason)
std::unique_ptr< pretty_printer > m_pp
Definition analyzer-logging.h:80
void void void end_log_line()
void void exit_scope(const char *scope_name)
const text_art::theme * get_text_art_theme() const
Definition analyzer-logging.h:58
Definition pretty-print.h:241
Definition canvas.h:38
#define ATTRIBUTE_GCC_DIAG(m, n)
Definition diagnostic-core.h:71
Definition access-diagram.h:30
Definition analyzer-logging.h:28
static void const char va_list ap
Definition read-md.cc:205
#define gcc_assert(EXPR)
Definition system.h:772