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_TRACE_EVENT_TRACE_CATEGORY_H_
6 #define BASE_TRACE_EVENT_TRACE_CATEGORY_H_
7 
8 #include <stdint.h>
9 
10 namespace base {
11 namespace trace_event {
12 
13 // Captures the state of an invidivual trace category. Nothing except tracing
14 // internals (e.g., TraceLog) is supposed to have non-const Category pointers.
15 struct TraceCategory {
16   // The TRACE_EVENT macros should only use this value as a bool.
17   // These enum values are effectively a public API and third_party projects
18   // depend on their value. Hence, never remove or recycle existing bits, unless
19   // you are sure that all the third-party projects that depend on this have
20   // been updated.
21   enum StateFlags : uint8_t {
22     ENABLED_FOR_RECORDING = 1 << 0,
23 
24     // Not used anymore.
25     DEPRECATED_ENABLED_FOR_MONITORING = 1 << 1,
26     DEPRECATED_ENABLED_FOR_EVENT_CALLBACK = 1 << 2,
27 
28     ENABLED_FOR_ETW_EXPORT = 1 << 3,
29     ENABLED_FOR_FILTERING = 1 << 4
30   };
31 
FromStatePtrTraceCategory32   static const TraceCategory* FromStatePtr(const uint8_t* state_ptr) {
33     static_assert(
34         offsetof(TraceCategory, state_) == 0,
35         "|state_| must be the first field of the TraceCategory class.");
36     return reinterpret_cast<const TraceCategory*>(state_ptr);
37   }
38 
is_validTraceCategory39   bool is_valid() const { return name_ != nullptr; }
set_nameTraceCategory40   void set_name(const char* name) { name_ = name; }
nameTraceCategory41   const char* name() const {
42     DCHECK(is_valid());
43     return name_;
44   }
45 
46   // TODO(primiano): This is an intermediate solution to deal with the fact that
47   // today TRACE_EVENT* macros cache the state ptr. They should just cache the
48   // full TraceCategory ptr, which is immutable, and use these helper function
49   // here. This will get rid of the need of this awkward ptr getter completely.
state_ptrTraceCategory50   constexpr const uint8_t* state_ptr() const {
51     return const_cast<const uint8_t*>(&state_);
52   }
53 
stateTraceCategory54   uint8_t state() const {
55     return *const_cast<volatile const uint8_t*>(&state_);
56   }
57 
is_enabledTraceCategory58   bool is_enabled() const { return state() != 0; }
59 
set_stateTraceCategory60   void set_state(uint8_t state) {
61     *const_cast<volatile uint8_t*>(&state_) = state;
62   }
63 
clear_state_flagTraceCategory64   void clear_state_flag(StateFlags flag) { set_state(state() & (~flag)); }
set_state_flagTraceCategory65   void set_state_flag(StateFlags flag) { set_state(state() | flag); }
66 
enabled_filtersTraceCategory67   uint32_t enabled_filters() const {
68     return *const_cast<volatile const uint32_t*>(&enabled_filters_);
69   }
70 
is_filter_enabledTraceCategory71   bool is_filter_enabled(size_t index) const {
72     DCHECK(index < sizeof(enabled_filters_) * 8);
73     return (enabled_filters() & (1 << index)) != 0;
74   }
75 
set_enabled_filtersTraceCategory76   void set_enabled_filters(uint32_t enabled_filters) {
77     *const_cast<volatile uint32_t*>(&enabled_filters_) = enabled_filters;
78   }
79 
reset_for_testingTraceCategory80   void reset_for_testing() {
81     set_state(0);
82     set_enabled_filters(0);
83   }
84 
85   // These fields should not be accessed directly, not even by tracing code.
86   // The only reason why these are not private is because it makes it impossible
87   // to have a global array of TraceCategory in category_registry.cc without
88   // creating initializers. See discussion on goo.gl/qhZN94 and
89   // crbug.com/{660967,660828}.
90 
91   // The enabled state. TRACE_EVENT* macros will capture events if any of the
92   // flags here are set. Since TRACE_EVENTx macros are used in a lot of
93   // fast-paths, accesses to this field are non-barriered and racy by design.
94   // This field is mutated when starting/stopping tracing and we don't care
95   // about missing some events.
96   uint8_t state_;
97 
98   // When ENABLED_FOR_FILTERING is set, this contains a bitmap to the
99   // corresponding filter (see event_filters.h).
100   uint32_t enabled_filters_;
101 
102   // TraceCategory group names are long lived static strings.
103   const char* name_;
104 };
105 
106 }  // namespace trace_event
107 }  // namespace base
108 
109 #endif  // BASE_TRACE_EVENT_TRACE_CATEGORY_H_
110