1// Copyright (c) 2006-2009 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Defines the VLOG_IS_ON macro that controls the variable-verbosity
6// conditional logging.
7//
8// It's used by VLOG and VLOG_IF in logging.h
9// and by RAW_VLOG in raw_logging.h to trigger the logging.
10//
11// It can also be used directly e.g. like this:
12//   if (VLOG_IS_ON(2)) {
13//     // do some logging preparation and logging
14//     // that can't be accomplished e.g. via just VLOG(2) << ...;
15//   }
16//
17// The truth value that VLOG_IS_ON(level) returns is determined by
18// the three verbosity level flags:
19//   --v=<n>  Gives the default maximal active V-logging level;
20//            0 is the default.
21//            Normally positive values are used for V-logging levels.
22//   --vmodule=<str>  Gives the per-module maximal V-logging levels to override
23//                    the value given by --v.
24//                    E.g. "my_module=2,foo*=3" would change the logging level
25//                    for all code in source files "my_module.*" and "foo*.*"
26//                    ("-inl" suffixes are also disregarded for this matching).
27//   --silent_init  When true has the effect of increasing
28//                  the argument of VLOG_IS_ON by 1,
29//                  thus suppressing one more level of verbose logging.
30//
31// SetVLOGLevel helper function is provided to do limited dynamic control over
32// V-logging by overriding the per-module settings given via --vmodule flag.
33//
34// CAVEAT: --vmodule functionality is not available in non gcc compilers.
35//
36
37#ifndef BASE_VLOG_IS_ON_H_
38#define BASE_VLOG_IS_ON_H_
39
40#include "base/atomicops.h"
41#include "base/basictypes.h"
42#include "base/port.h"
43#include "base/commandlineflags.h"
44#include "base/log_severity.h"
45
46DECLARE_int32(v);  // in vlog_is_on.cc
47DECLARE_bool(silent_init);  // in google.cc
48
49#if defined(__GNUC__)
50// We pack an int16 verbosity level and an int16 epoch into an
51// Atomic32 at every VLOG_IS_ON() call site.  The level determines
52// whether the site should log, and the epoch determines whether the
53// site is stale and should be reinitialized.  A verbosity level of
54// kUseFlag (-1) indicates that the value of FLAGS_v should be used as
55// the verbosity level.  When the site is (re)initialized, a verbosity
56// level for the current source file is retrieved from an internal
57// list.  This list is mutated through calls to SetVLOGLevel() and
58// mutations to the --vmodule flag.  New log sites are initialized
59// with a stale epoch and a verbosity level of kUseFlag.
60//
61// TODO(llansing): Investigate using GCC's __builtin_constant_p() to
62// generate less code at call sites where verbositylevel is known to
63// be a compile-time constant.
64#define VLOG_IS_ON(verboselevel)                                               \
65  ({ static Atomic32 site__ = ::base::internal::kDefaultSite;                  \
66     ::base::internal::VLogEnabled(&site__, (verboselevel), __FILE__); })
67#else
68// GNU extensions not available, so we do not support --vmodule.
69// Dynamic value of FLAGS_v always controls the logging level.
70//
71// TODO(llansing): Investigate supporting --vmodule on other platforms.
72#define VLOG_IS_ON(verboselevel)                                               \
73  (FLAGS_v >= (verboselevel) + FLAGS_silent_init)
74#endif
75
76// Set VLOG(_IS_ON) level for module_pattern to log_level.
77// This lets us dynamically control what is normally set by the --vmodule flag.
78// Returns the level that previously applied to module_pattern.
79// NOTE: To change the log level for VLOG(_IS_ON) sites
80//       that have already executed after/during InitGoogle,
81//       one needs to supply the exact --vmodule pattern that applied to them.
82//       (If no --vmodule pattern applied to them
83//       the value of FLAGS_v will continue to control them.)
84int SetVLOGLevel(const char* module_pattern, int log_level);
85
86// Private implementation details.  No user-serviceable parts inside.
87namespace base {
88namespace internal {
89
90// Each log site determines whether its log level is up to date by
91// comparing its epoch to this global epoch.  Whenever the program's
92// vmodule configuration changes (ex: SetVLOGLevel is called), the
93// global epoch is advanced, invalidating all site epochs.
94extern Atomic32 vlog_epoch;
95
96// A log level of kUseFlag means "read the logging level from FLAGS_v."
97const int kUseFlag = -1;
98
99// Log sites use FLAGS_v by default, and have an initial epoch of 0.
100const Atomic32 kDefaultSite = kUseFlag << 16;
101
102// The global epoch is the least significant half of an Atomic32, and
103// may only be accessed through atomic operations.
104inline Atomic32 GlobalEpoch() {
105  return Acquire_Load(&vlog_epoch) & 0x0000FFFF;
106}
107
108// The least significant half of a site is the epoch.
109inline int SiteEpoch(Atomic32 site) { return site & 0x0000FFFF; }
110
111// The most significant half of a site is the logging level.
112inline int SiteLevel(Atomic32 site) { return site >> 16; }
113
114// Construct a logging site from a logging level and epoch.
115inline Atomic32 Site(int level, int epoch) {
116  return ((level & 0x0000FFFF) << 16) | (epoch & 0x0000FFFF);
117}
118
119// Attempt to initialize or reinitialize a VLOG site.  Returns the
120// level of the log site, regardless of whether the attempt succeeds
121// or fails.
122//   site: The address of the log site's state.
123//   fname: The filename of the current source file.
124int InitVLOG(Atomic32* site, const char* fname);
125
126// Determine whether verbose logging should occur at a given log site.
127//
128// TODO(llansing): Find a way to eliminate FLAGS_silent_init from this
129// function while preserving the silent initialization behavior.  The
130// common-case code path shouldn't pay for silent initialization.
131inline bool VLogEnabled(Atomic32* site, int32 level, const char* const file) {
132  const Atomic32 site_copy = Acquire_Load(site);
133  const int32 site_level =
134      PREDICT_TRUE(SiteEpoch(site_copy) == GlobalEpoch()) ?
135      SiteLevel(site_copy) : InitVLOG(site, file);
136  return (site_level == kUseFlag ? FLAGS_v : site_level) >=
137      (level + FLAGS_silent_init);
138}
139
140}  // namespace internal
141}  // namespace base
142
143#endif  // BASE_VLOG_IS_ON_H_
144