Stream.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
3 *
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
7 */
8
9/* DEBUG: section 00 Debug Routines */
10
11#ifndef SQUID_SRC_DEBUG_STREAM_H
12#define SQUID_SRC_DEBUG_STREAM_H
13
14#include "base/Here.h"
15// XXX should be mem/forward.h once it removes dependencies on typedefs.h
16#include "mem/AllocatorProxy.h"
17
18#include <iostream>
19#undef assert
20#include <sstream>
21#include <iomanip>
22#if defined(assert)
23#undef assert
24#endif
25#if PURIFY
26#define assert(EX) ((void)0)
27#elif defined(NODEBUG)
28#define assert(EX) ((void)0)
29#else
30#define assert(EX) ((EX)?((void)0):xassert( # EX , __FILE__, __LINE__))
31#endif
32
33/* defined debug section limits */
34#define MAX_DEBUG_SECTIONS 100
35
36/* defined names for Debug Levels */
37#define DBG_CRITICAL 0
38#define DBG_IMPORTANT 1
39/* levels 2-8 are still being discussed amongst the developers */
40#define DBG_DATA 9
42#define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
45
46class Debug
47{
48
49public:
51 class Context
52 {
53 public:
54 Context(const int aSectionLevel, const int aLevel);
55
56 int section;
57 int level;
59
60 private:
61 friend class Debug;
62 friend class DebugMessageHeader;
63
64 void rewind(const int aSection, const int aLevel);
65 void formatStream();
67 std::ostringstream buf;
69
73 };
74
76 static bool Enabled(const int section, const int level)
77 {
78 return level <= Debug::Levels[section];
79 }
80
81 static char *debugOptions;
82 static char *cache_log;
83 static int rotateNumber;
85 static int override_X;
86 static bool log_syslog;
87
88 // TODO: Convert all helpers to use debugs() and NameThisHelper() APIs.
92 static void NameThisHelper(const char *name);
93
96 static void NameThisKid(int kidIdentifier);
97
98 static void parseOptions(char const *);
99
101 static int Level() { return Current ? Current->level : 1; }
103 static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
104
106 static std::ostringstream &Start(const int section, const int level);
108 static void Finish();
109
111 static void ForceAlert();
112
114 static std::ostream& Extra(std::ostream &os) { return os << "\n "; }
115
117 static void ForgetSaved();
118
122 static void PrepareToDie();
123
125 static void LogWaitingForIdle();
126
127 /* cache_log channel */
128
132 static void BanCacheLogUse();
133
137 static void UseCacheLog();
138
141 static void StopCacheLogUse();
142
143 /* stderr channel */
144
149 static void EnsureDefaultStderrLevel(int maxDefault);
150
153 static void ResetStderrLevel(int maxLevel);
154
157 static void SettleStderr();
158
161 static bool StderrEnabled();
162
163 /* syslog channel */
164
166 static void ConfigureSyslog(const char *facility);
167
170 static void SettleSyslog();
171
172private:
173 static void LogMessage(const Context &);
174
175 static Context *Current;
176};
177
180FILE *DebugStream();
182#define debug_log DebugStream()
183
185void ResyncDebugLog(FILE *newDestination);
186
187/* Debug stream
188 *
189 * Unit tests can enable full debugging to stderr for one
190 * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
191 * section number before any header
192 */
193#define debugs(SECTION, LEVEL, CONTENT) \
194 do { \
195 const int _dbg_level = (LEVEL); \
196 if (Debug::Enabled((SECTION), _dbg_level)) { \
197 std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
198 if (_dbg_level > DBG_IMPORTANT) { \
199 _dbo << (SECTION) << ',' << _dbg_level << "| " \
200 << Here() << ": "; \
201 } \
202 _dbo << CONTENT; \
203 Debug::Finish(); \
204 } \
205 } while (/*CONSTCOND*/ 0)
206
210std::ostream& ForceAlert(std::ostream& s);
211
221inline std::ostream&
222HERE(std::ostream& s)
223{
224 return s;
225}
226
227/*
228 * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
229 *
230 * debugs(1,1, MYNAME << "WARNING: some message");
231 */
232#ifdef __PRETTY_FUNCTION__
233#define MYNAME __PRETTY_FUNCTION__ << " "
234#else
235#define MYNAME __FUNCTION__ << " "
236#endif
237
238/* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
239inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
240{
241 return (os << (int)d);
242}
243
244/* Legacy debug function definitions */
245void _db_rotate_log(void);
246
247#endif /* SQUID_SRC_DEBUG_STREAM_H */
248
meta-information of a Finish()ed debugs() message
Definition: debug.cc:107
int section
debugs() section
Definition: debug.cc:113
int level
debugs() level
Definition: debug.cc:114
meta-information for debugs() or a similar debugging call
Definition: Stream.h:52
int section
the debug section of the debugs() call
Definition: Stream.h:56
bool waitingForIdle
Definition: Stream.h:72
Context * upper
previous or parent record in nested debugging calls
Definition: Stream.h:66
int sectionLevel
maximum debugging level allowed during the call
Definition: Stream.h:58
std::ostringstream buf
debugs() output sink
Definition: Stream.h:67
int level
minimum debugging level required by the debugs() call
Definition: Stream.h:57
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Stream.h:68
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:1302
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:1285
Context(const int aSectionLevel, const int aLevel)
Definition: debug.cc:1272
Definition: Stream.h:47
static void ResetStderrLevel(int maxLevel)
Definition: debug.cc:699
static bool StderrEnabled()
Definition: debug.cc:725
static bool log_syslog
Definition: Stream.h:86
static void parseOptions(char const *)
Definition: debug.cc:1091
static void PrepareToDie()
Definition: debug.cc:561
static void ForgetSaved()
silently erases saved early debugs() messages (if any)
Definition: debug.cc:552
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Stream.h:76
static Context * Current
deepest active context; nil outside debugs()
Definition: Stream.h:175
static void NameThisKid(int kidIdentifier)
Definition: debug.cc:405
static int SectionLevel()
maximum level currently allowed
Definition: Stream.h:103
static void LogMessage(const Context &)
broadcasts debugs() message to the logging channels
Definition: debug.cc:777
static int override_X
Definition: Stream.h:85
static void SettleSyslog()
Definition: debug.cc:1141
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Stream.h:84
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:1352
static void NameThisHelper(const char *name)
Definition: debug.cc:382
static char * debugOptions
Definition: Stream.h:81
static void UseCacheLog()
Definition: debug.cc:1121
static char * cache_log
Definition: Stream.h:82
static std::ostringstream & Start(const int section, const int level)
opens debugging context and returns output buffer
Definition: debug.cc:1328
static std::ostream & Extra(std::ostream &os)
prefixes each grouped debugs() line after the first one in the group
Definition: Stream.h:114
static void BanCacheLogUse()
Definition: debug.cc:1114
static void ConfigureSyslog(const char *facility)
enables logging to syslog (using the specified facility, when not nil)
Definition: debug.cc:1079
static void StopCacheLogUse()
Definition: debug.cc:1128
static int Level()
minimum level required by the current debugs() call
Definition: Stream.h:101
static int rotateNumber
Definition: Stream.h:83
static void EnsureDefaultStderrLevel(int maxDefault)
Definition: debug.cc:691
static void SettleStderr()
Definition: debug.cc:705
static void LogWaitingForIdle()
Logs messages of Finish()ed debugs() calls that were queued earlier.
Definition: debug.cc:1313
static void ForceAlert()
configures the active debugging context to write syslog ALERT
Definition: debug.cc:1389
FILE * DebugStream()
Definition: debug.cc:353
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:513
std::ostream & HERE(std::ostream &s)
Definition: Stream.h:222
#define MAX_DEBUG_SECTIONS
Definition: Stream.h:34
void _db_rotate_log(void)
Definition: debug.cc:1156
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Stream.h:239
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:1397

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors