Coverage Report

Created: 2024-09-23 06:29

/src/abseil-cpp/absl/log/globals.h
Line
Count
Source (jump to first uncovered line)
1
// Copyright 2022 The Abseil Authors.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      https://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14
//
15
// -----------------------------------------------------------------------------
16
// File: log/globals.h
17
// -----------------------------------------------------------------------------
18
//
19
// This header declares global logging library configuration knobs.
20
21
#ifndef ABSL_LOG_GLOBALS_H_
22
#define ABSL_LOG_GLOBALS_H_
23
24
#include "absl/base/attributes.h"
25
#include "absl/base/config.h"
26
#include "absl/base/log_severity.h"
27
#include "absl/log/internal/vlog_config.h"
28
#include "absl/strings/string_view.h"
29
30
namespace absl {
31
ABSL_NAMESPACE_BEGIN
32
33
//------------------------------------------------------------------------------
34
//  Minimum Log Level
35
//------------------------------------------------------------------------------
36
//
37
// Messages logged at or above this severity are directed to all registered log
38
// sinks or skipped otherwise. This parameter can also be modified using
39
// command line flag --minloglevel.
40
// See absl/base/log_severity.h for descriptions of severity levels.
41
42
// MinLogLevel()
43
//
44
// Returns the value of the Minimum Log Level parameter.
45
// This function is async-signal-safe.
46
ABSL_MUST_USE_RESULT absl::LogSeverityAtLeast MinLogLevel();
47
48
// SetMinLogLevel()
49
//
50
// Updates the value of Minimum Log Level parameter.
51
// This function is async-signal-safe.
52
void SetMinLogLevel(absl::LogSeverityAtLeast severity);
53
54
namespace log_internal {
55
56
// ScopedMinLogLevel
57
//
58
// RAII type used to temporarily update the Min Log Level parameter.
59
class ScopedMinLogLevel final {
60
 public:
61
  explicit ScopedMinLogLevel(absl::LogSeverityAtLeast severity);
62
  ScopedMinLogLevel(const ScopedMinLogLevel&) = delete;
63
  ScopedMinLogLevel& operator=(const ScopedMinLogLevel&) = delete;
64
  ~ScopedMinLogLevel();
65
66
 private:
67
  absl::LogSeverityAtLeast saved_severity_;
68
};
69
70
}  // namespace log_internal
71
72
//------------------------------------------------------------------------------
73
// Stderr Threshold
74
//------------------------------------------------------------------------------
75
//
76
// Messages logged at or above this level are directed to stderr in
77
// addition to other registered log sinks. This parameter can also be modified
78
// using command line flag --stderrthreshold.
79
// See absl/base/log_severity.h for descriptions of severity levels.
80
81
// StderrThreshold()
82
//
83
// Returns the value of the Stderr Threshold parameter.
84
// This function is async-signal-safe.
85
ABSL_MUST_USE_RESULT absl::LogSeverityAtLeast StderrThreshold();
86
87
// SetStderrThreshold()
88
//
89
// Updates the Stderr Threshold parameter.
90
// This function is async-signal-safe.
91
void SetStderrThreshold(absl::LogSeverityAtLeast severity);
92
0
inline void SetStderrThreshold(absl::LogSeverity severity) {
93
0
  absl::SetStderrThreshold(static_cast<absl::LogSeverityAtLeast>(severity));
94
0
}
95
96
// ScopedStderrThreshold
97
//
98
// RAII type used to temporarily update the Stderr Threshold parameter.
99
class ScopedStderrThreshold final {
100
 public:
101
  explicit ScopedStderrThreshold(absl::LogSeverityAtLeast severity);
102
  ScopedStderrThreshold(const ScopedStderrThreshold&) = delete;
103
  ScopedStderrThreshold& operator=(const ScopedStderrThreshold&) = delete;
104
  ~ScopedStderrThreshold();
105
106
 private:
107
  absl::LogSeverityAtLeast saved_severity_;
108
};
109
110
//------------------------------------------------------------------------------
111
// Log Backtrace At
112
//------------------------------------------------------------------------------
113
//
114
// Users can request an existing `LOG` statement, specified by file and line
115
// number, to also include a backtrace when logged.
116
117
// ShouldLogBacktraceAt()
118
//
119
// Returns true if we should log a backtrace at the specified location.
120
namespace log_internal {
121
ABSL_MUST_USE_RESULT bool ShouldLogBacktraceAt(absl::string_view file,
122
                                               int line);
123
}  // namespace log_internal
124
125
// SetLogBacktraceLocation()
126
//
127
// Sets the location the backtrace should be logged at.  If the specified
128
// location isn't a `LOG` statement, the effect will be the same as
129
// `ClearLogBacktraceLocation` (but less efficient).
130
void SetLogBacktraceLocation(absl::string_view file, int line);
131
132
// ClearLogBacktraceLocation()
133
//
134
// Clears the set location so that backtraces will no longer be logged at it.
135
void ClearLogBacktraceLocation();
136
137
//------------------------------------------------------------------------------
138
// Prepend Log Prefix
139
//------------------------------------------------------------------------------
140
//
141
// This option tells the logging library that every logged message
142
// should include the prefix (severity, date, time, PID, etc.)
143
//
144
// ShouldPrependLogPrefix()
145
//
146
// Returns the value of the Prepend Log Prefix option.
147
// This function is async-signal-safe.
148
ABSL_MUST_USE_RESULT bool ShouldPrependLogPrefix();
149
150
// EnableLogPrefix()
151
//
152
// Updates the value of the Prepend Log Prefix option.
153
// This function is async-signal-safe.
154
void EnableLogPrefix(bool on_off);
155
156
//------------------------------------------------------------------------------
157
// `VLOG` Configuration
158
//------------------------------------------------------------------------------
159
//
160
// These methods set the `(ABSL_)VLOG(_IS_ON)` threshold.  They allow
161
// programmatic control of the thresholds set by the --v and --vmodule flags.
162
//
163
// Only `VLOG`s with a severity level LESS THAN OR EQUAL TO the threshold will
164
// be evaluated.
165
//
166
// For example, if the threshold is 2, then:
167
//
168
//   VLOG(2) << "This message will be logged.";
169
//   VLOG(3) << "This message will NOT be logged.";
170
//
171
// The default threshold is 0. Since `VLOG` levels must not be negative, a
172
// negative threshold value will turn off all VLOGs.
173
174
// SetGlobalVLogLevel()
175
//
176
// Sets the global `VLOG` level to threshold. Returns the previous global
177
// threshold.
178
0
inline int SetGlobalVLogLevel(int threshold) {
179
0
  return absl::log_internal::UpdateGlobalVLogLevel(threshold);
180
0
}
181
182
// SetVLogLevel()
183
//
184
// Sets the `VLOG` threshold for all files that match `module_pattern`,
185
// overwriting any prior value. Files that don't match aren't affected.
186
// Returns the threshold that previously applied to `module_pattern`.
187
0
inline int SetVLogLevel(absl::string_view module_pattern, int threshold) {
188
0
  return absl::log_internal::PrependVModule(module_pattern, threshold);
189
0
}
190
191
//------------------------------------------------------------------------------
192
// Configure Android Native Log Tag
193
//------------------------------------------------------------------------------
194
//
195
// The logging library forwards to the Android system log API when built for
196
// Android.  That API takes a string "tag" value in addition to a message and
197
// severity level.  The tag is used to identify the source of messages and to
198
// filter them.  This library uses the tag "native" by default.
199
200
// SetAndroidNativeTag()
201
//
202
// Stores a copy of the string pointed to by `tag` and uses it as the Android
203
// logging tag thereafter. `tag` must not be null.
204
// This function must not be called more than once!
205
void SetAndroidNativeTag(const char* tag);
206
207
namespace log_internal {
208
// GetAndroidNativeTag()
209
//
210
// Returns the configured Android logging tag.
211
const char* GetAndroidNativeTag();
212
}  // namespace log_internal
213
214
namespace log_internal {
215
216
using LoggingGlobalsListener = void (*)();
217
void SetLoggingGlobalsListener(LoggingGlobalsListener l);
218
219
// Internal implementation for the setter routines. These are used
220
// to break circular dependencies between flags and globals. Each "Raw"
221
// routine corresponds to the non-"Raw" counterpart and used to set the
222
// configuration parameter directly without calling back to the listener.
223
void RawSetMinLogLevel(absl::LogSeverityAtLeast severity);
224
void RawSetStderrThreshold(absl::LogSeverityAtLeast severity);
225
void RawEnableLogPrefix(bool on_off);
226
227
}  // namespace log_internal
228
ABSL_NAMESPACE_END
229
}  // namespace absl
230
231
#endif  // ABSL_LOG_GLOBALS_H_