1 // Copyright 2016 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 #ifndef BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_ 6 #define BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_ 7 8 #include <stdint.h> 9 10 #include <limits> 11 #include <type_traits> 12 13 #include "base/atomicops.h" 14 #include "base/logging.h" 15 #include "base/metrics/histogram.h" 16 #include "base/metrics/sparse_histogram.h" 17 #include "base/time/time.h" 18 19 // This is for macros internal to base/metrics. They should not be used outside 20 // of this directory. For writing to UMA histograms, see histogram_macros.h. 21 22 // TODO(rkaplow): Improve commenting of these methods. 23 24 //------------------------------------------------------------------------------ 25 // Histograms are often put in areas where they are called many many times, and 26 // performance is critical. As a result, they are designed to have a very low 27 // recurring cost of executing (adding additional samples). Toward that end, 28 // the macros declare a static pointer to the histogram in question, and only 29 // take a "slow path" to construct (or find) the histogram on the first run 30 // through the macro. We leak the histograms at shutdown time so that we don't 31 // have to validate using the pointers at any time during the running of the 32 // process. 33 34 35 // In some cases (integration into 3rd party code), it's useful to separate the 36 // definition of |atomic_histogram_pointer| from its use. To achieve this we 37 // define HISTOGRAM_POINTER_USE, which uses an |atomic_histogram_pointer|, and 38 // STATIC_HISTOGRAM_POINTER_BLOCK, which defines an |atomic_histogram_pointer| 39 // and forwards to HISTOGRAM_POINTER_USE. 40 #define HISTOGRAM_POINTER_USE(atomic_histogram_pointer, \ 41 constant_histogram_name, \ 42 histogram_add_method_invocation, \ 43 histogram_factory_get_invocation) \ 44 do { \ 45 /* \ 46 * Acquire_Load() ensures that we acquire visibility to the \ 47 * pointed-to data in the histogram. \ 48 */ \ 49 base::HistogramBase* histogram_pointer( \ 50 reinterpret_cast<base::HistogramBase*>( \ 51 base::subtle::Acquire_Load(atomic_histogram_pointer))); \ 52 if (!histogram_pointer) { \ 53 /* \ 54 * This is the slow path, which will construct OR find the \ 55 * matching histogram. histogram_factory_get_invocation includes \ 56 * locks on a global histogram name map and is completely thread \ 57 * safe. \ 58 */ \ 59 histogram_pointer = histogram_factory_get_invocation; \ 60 \ 61 /* \ 62 * Use Release_Store to ensure that the histogram data is made \ 63 * available globally before we make the pointer visible. Several \ 64 * threads may perform this store, but the same value will be \ 65 * stored in all cases (for a given named/spec'ed histogram). \ 66 * We could do this without any barrier, since FactoryGet entered \ 67 * and exited a lock after construction, but this barrier makes \ 68 * things clear. \ 69 */ \ 70 base::subtle::Release_Store( \ 71 atomic_histogram_pointer, \ 72 reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer)); \ 73 } \ 74 if (DCHECK_IS_ON()) \ 75 histogram_pointer->CheckName(constant_histogram_name); \ 76 histogram_pointer->histogram_add_method_invocation; \ 77 } while (0) 78 79 // This is a helper macro used by other macros and shouldn't be used directly. 80 // Defines the static |atomic_histogram_pointer| and forwards to 81 // HISTOGRAM_POINTER_USE. 82 #define STATIC_HISTOGRAM_POINTER_BLOCK(constant_histogram_name, \ 83 histogram_add_method_invocation, \ 84 histogram_factory_get_invocation) \ 85 do { \ 86 /* \ 87 * The pointer's presence indicates that the initialization is complete. \ 88 * Initialization is idempotent, so it can safely be atomically repeated. \ 89 */ \ 90 static base::subtle::AtomicWord atomic_histogram_pointer = 0; \ 91 HISTOGRAM_POINTER_USE(&atomic_histogram_pointer, constant_histogram_name, \ 92 histogram_add_method_invocation, \ 93 histogram_factory_get_invocation); \ 94 } while (0) 95 96 // This is a helper macro used by other macros and shouldn't be used directly. 97 #define INTERNAL_HISTOGRAM_CUSTOM_COUNTS_WITH_FLAG(name, sample, min, max, \ 98 bucket_count, flag) \ 99 STATIC_HISTOGRAM_POINTER_BLOCK( \ 100 name, Add(sample), \ 101 base::Histogram::FactoryGet(name, min, max, bucket_count, flag)) 102 103 // This is a helper macro used by other macros and shouldn't be used directly. 104 // The bucketing scheme is linear with a bucket size of 1. For N items, 105 // recording values in the range [0, N - 1] creates a linear histogram with N + 106 // 1 buckets: 107 // [0, 1), [1, 2), ..., [N - 1, N) 108 // and an overflow bucket [N, infinity). 109 // 110 // Code should never emit to the overflow bucket; only to the other N buckets. 111 // This allows future versions of Chrome to safely increase the boundary size. 112 // Otherwise, the histogram would have [N - 1, infinity) as its overflow bucket, 113 // and so the maximal value (N - 1) would be emitted to this overflow bucket. 114 // But, if an additional value were later added, the bucket label for 115 // the value (N - 1) would change to [N - 1, N), which would result in different 116 // versions of Chrome using different bucket labels for identical data. 117 #define INTERNAL_HISTOGRAM_EXACT_LINEAR_WITH_FLAG(name, sample, boundary, \ 118 flag) \ 119 do { \ 120 static_assert(!std::is_enum<decltype(sample)>::value, \ 121 "|sample| should not be an enum type!"); \ 122 static_assert(!std::is_enum<decltype(boundary)>::value, \ 123 "|boundary| should not be an enum type!"); \ 124 STATIC_HISTOGRAM_POINTER_BLOCK( \ 125 name, Add(sample), \ 126 base::LinearHistogram::FactoryGet(name, 1, boundary, boundary + 1, \ 127 flag)); \ 128 } while (0) 129 130 // Similar to the previous macro but intended for enumerations. This delegates 131 // the work to the previous macro, but supports scoped enumerations as well by 132 // forcing an explicit cast to the HistogramBase::Sample integral type. 133 // 134 // Note the range checks verify two separate issues: 135 // - that the declared enum max isn't out of range of HistogramBase::Sample 136 // - that the declared enum max is > 0 137 // 138 // TODO(dcheng): This should assert that the passed in types are actually enum 139 // types. 140 #define INTERNAL_HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary, flag) \ 141 do { \ 142 static_assert( \ 143 !std::is_enum<decltype(sample)>::value || \ 144 !std::is_enum<decltype(boundary)>::value || \ 145 std::is_same<std::remove_const<decltype(sample)>::type, \ 146 std::remove_const<decltype(boundary)>::type>::value, \ 147 "|sample| and |boundary| shouldn't be of different enums"); \ 148 static_assert( \ 149 static_cast<uintmax_t>(boundary) < \ 150 static_cast<uintmax_t>( \ 151 std::numeric_limits<base::HistogramBase::Sample>::max()), \ 152 "|boundary| is out of range of HistogramBase::Sample"); \ 153 INTERNAL_HISTOGRAM_EXACT_LINEAR_WITH_FLAG( \ 154 name, static_cast<base::HistogramBase::Sample>(sample), \ 155 static_cast<base::HistogramBase::Sample>(boundary), flag); \ 156 } while (0) 157 158 // This is a helper macro used by other macros and shouldn't be used directly. 159 // This is necessary to expand __COUNTER__ to an actual value. 160 #define INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER(name, is_long, key) \ 161 INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_UNIQUE(name, is_long, key) 162 163 // This is a helper macro used by other macros and shouldn't be used directly. 164 #define INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_UNIQUE(name, is_long, key) \ 165 class ScopedHistogramTimer##key { \ 166 public: \ 167 ScopedHistogramTimer##key() : constructed_(base::TimeTicks::Now()) {} \ 168 ~ScopedHistogramTimer##key() { \ 169 base::TimeDelta elapsed = base::TimeTicks::Now() - constructed_; \ 170 if (is_long) { \ 171 UMA_HISTOGRAM_LONG_TIMES_100(name, elapsed); \ 172 } else { \ 173 UMA_HISTOGRAM_TIMES(name, elapsed); \ 174 } \ 175 } \ 176 private: \ 177 base::TimeTicks constructed_; \ 178 } scoped_histogram_timer_##key 179 180 // Macro for sparse histogram. 181 // The implementation is more costly to add values to, and each value 182 // stored has more overhead, compared to the other histogram types. However it 183 // may be more efficient in memory if the total number of sample values is small 184 // compared to the range of their values. 185 #define INTERNAL_HISTOGRAM_SPARSE_SLOWLY(name, sample) \ 186 do { \ 187 base::HistogramBase* histogram = base::SparseHistogram::FactoryGet( \ 188 name, base::HistogramBase::kUmaTargetedHistogramFlag); \ 189 histogram->Add(sample); \ 190 } while (0) 191 192 #endif // BASE_METRICS_HISTOGRAM_MACROS_INTERNAL_H_ 193
