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);
66 std::ostringstream buf;
68
72 };
73
75 static bool Enabled(const int section, const int level)
76 {
77 return level <= Debug::Levels[section];
78 }
79
80 static char *debugOptions;
81 static char *cache_log;
82 static int rotateNumber;
84 static int override_X;
85 static bool log_syslog;
86
87 // TODO: Convert all helpers to use debugs() and NameThisHelper() APIs.
91 static void NameThisHelper(const char *name);
92
95 static void NameThisKid(int kidIdentifier);
96
97 static void parseOptions(char const *);
98
100 static int Level() { return Current ? Current->level : 1; }
102 static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
103
105 static std::ostringstream &Start(const int section, const int level);
107 static void Finish();
108
110 static void ForceAlert();
111
114 static std::ostream& Extra(std::ostream &);
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 FormatStream(std::ostream &);
174 static void LogMessage(const Context &);
175
176 static Context *Current;
177};
178
181FILE *DebugStream();
183#define debug_log DebugStream()
184
186void ResyncDebugLog(FILE *newDestination);
187
188/* Debug stream
189 *
190 * Unit tests can enable full debugging to stderr for one
191 * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
192 * section number before any header
193 */
194#define debugs(SECTION, LEVEL, CONTENT) \
195 do { \
196 const int _dbg_level = (LEVEL); \
197 if (Debug::Enabled((SECTION), _dbg_level)) { \
198 std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
199 if (_dbg_level > DBG_IMPORTANT) { \
200 _dbo << (SECTION) << ',' << _dbg_level << "| " \
201 << Here() << ": "; \
202 } \
203 _dbo << CONTENT; \
204 Debug::Finish(); \
205 } \
206 } while (/*CONSTCOND*/ 0)
207
211std::ostream& ForceAlert(std::ostream& s);
212
222inline std::ostream&
223HERE(std::ostream& s)
224{
225 return s;
226}
227
228/*
229 * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
230 *
231 * debugs(1,1, MYNAME << "WARNING: some message");
232 */
233#ifdef __PRETTY_FUNCTION__
234#define MYNAME __PRETTY_FUNCTION__ << " "
235#else
236#define MYNAME __FUNCTION__ << " "
237#endif
238
239/* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
240inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
241{
242 return (os << (int)d);
243}
244
245/* Legacy debug function definitions */
246void _db_rotate_log(void);
247
248#endif /* SQUID_SRC_DEBUG_STREAM_H */
249
meta-information of a Finish()ed debugs() message
Definition: debug.cc:108
int section
debugs() section
Definition: debug.cc:114
int level
debugs() level
Definition: debug.cc:115
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:71
Context * upper
previous or parent record in nested debugging calls
Definition: Stream.h:65
int sectionLevel
maximum debugging level allowed during the call
Definition: Stream.h:58
std::ostringstream buf
debugs() output sink
Definition: Stream.h:66
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:67
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:1287
Context(const int aSectionLevel, const int aLevel)
Definition: debug.cc:1274
Definition: Stream.h:47
static void ResetStderrLevel(int maxLevel)
Definition: debug.cc:700
static bool StderrEnabled()
Definition: debug.cc:726
static bool log_syslog
Definition: Stream.h:85
static void parseOptions(char const *)
Definition: debug.cc:1092
static void PrepareToDie()
Definition: debug.cc:562
static void ForgetSaved()
silently erases saved early debugs() messages (if any)
Definition: debug.cc:553
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Stream.h:75
static Context * Current
deepest active context; nil outside debugs()
Definition: Stream.h:176
static std::ostream & Extra(std::ostream &)
Definition: debug.cc:1313
static void NameThisKid(int kidIdentifier)
Definition: debug.cc:406
static int SectionLevel()
maximum level currently allowed
Definition: Stream.h:102
static void LogMessage(const Context &)
broadcasts debugs() message to the logging channels
Definition: debug.cc:778
static int override_X
Definition: Stream.h:84
static void SettleSyslog()
Definition: debug.cc:1142
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Stream.h:83
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:1363
static void NameThisHelper(const char *name)
Definition: debug.cc:383
static char * debugOptions
Definition: Stream.h:80
static void UseCacheLog()
Definition: debug.cc:1122
static char * cache_log
Definition: Stream.h:81
static void FormatStream(std::ostream &)
configures default formatting for the debugging stream
Definition: debug.cc:1302
static std::ostringstream & Start(const int section, const int level)
opens debugging context and returns output buffer
Definition: debug.cc:1339
static void BanCacheLogUse()
Definition: debug.cc:1115
static void ConfigureSyslog(const char *facility)
enables logging to syslog (using the specified facility, when not nil)
Definition: debug.cc:1080
static void StopCacheLogUse()
Definition: debug.cc:1129
static int Level()
minimum level required by the current debugs() call
Definition: Stream.h:100
static int rotateNumber
Definition: Stream.h:82
static void EnsureDefaultStderrLevel(int maxDefault)
Definition: debug.cc:692
static void SettleStderr()
Definition: debug.cc:706
static void LogWaitingForIdle()
Logs messages of Finish()ed debugs() calls that were queued earlier.
Definition: debug.cc:1324
static void ForceAlert()
configures the active debugging context to write syslog ALERT
Definition: debug.cc:1400
FILE * DebugStream()
Definition: debug.cc:354
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:514
std::ostream & HERE(std::ostream &s)
Definition: Stream.h:223
#define MAX_DEBUG_SECTIONS
Definition: Stream.h:34
void _db_rotate_log(void)
Definition: debug.cc:1157
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Stream.h:240
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:1408

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors