HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
event.h
Go to the documentation of this file.
1 //
2 // Copyright 2018 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 
8 #ifndef PXR_BASE_TRACE_EVENT_H
9 #define PXR_BASE_TRACE_EVENT_H
10 
11 #include "pxr/pxr.h"
12 
13 #include "pxr/base/trace/api.h"
15 #include "pxr/base/trace/key.h"
16 
17 #include "pxr/base/arch/timing.h"
18 
20 
21 class TraceEventData;
22 
23 ////////////////////////////////////////////////////////////////////////////////
24 /// \class TraceEvent
25 ///
26 /// This represents an event recorded by a TraceCollector.
27 /// It contains a key (name), categoryId, timestamp, type, and optional
28 /// metadata.
29 ///
30 class TraceEvent {
31 public:
32  /// Time in "ticks".
33  using TimeStamp = uint64_t;
34  using Key = TraceKey;
35 
36  /// \name Tag enums to select constructors
37  /// @{
38  enum BeginTag { Begin };
39  enum EndTag { End };
41  enum MarkerTag { Marker };
44  enum DataTag { Data };
45  /// @}
46 
47  /// Valid event types
48  enum class EventType : uint8_t {
49  Unknown, ///< The event is an unknown type.
50  Begin, ///< The event represents the beginning timestamp of a scope.
51  End, ///< The event represents the ending timestamp of a scope.
52  Timespan, ///< The event represents begin and end timestamp of a scope.
53  Marker, ///< The event represents an marker without a duration.
54  CounterDelta, ///< The event represents a change in a counter.
55  CounterValue, ///< The event represents the value of a counter.
56  ScopeData,
57  ///< The event stores data that is associated with its enclosing scope.
58  };
59 
60  /// The different types of data that can be stored in a TraceEvent instance.
61  enum class DataType : uint8_t {
62  String, ///< The event is storing a string.
63  Boolean, ///< The event is storing a bool.
64  Int, ///< The event is storing an integer.
65  UInt, ///< The event is storing an unsigned integer.
66  Float, ///< The event is storing an double.
67  Invalid ///< The event is not storing any data.
68  };
69 
70  /// Return this event's key.
71  const Key& GetKey() const { return _key; }
72 
73  /// Return the time stamp associated with this event.
75 
76  /// Return the counter value associated with this event.
77  TRACE_API double GetCounterValue() const;
78 
79  /// Returns the event's category id.
80  TraceCategoryId GetCategory() const { return _category; }
81 
82  /// Returns the start time of a timespan event.
84 
85  /// Returns the end time of a timespan event.
87 
88  /// Returns the data stored in a data event.
90 
91  /// Returns the type of the event.
92  TRACE_API EventType GetType() const;
93 
94  /// \name Constructors
95  /// @{
96 
97  /// Constructor for Begin events that will automatically set the
98  /// timestamp from the current time.
99  TraceEvent(BeginTag, const Key& key, TraceCategoryId cat) :
100  _key(key),
101  _category(cat),
102  _type(_InternalEventType::Begin),
103  _time(ArchGetTickTime()) {
104  }
105 
106  /// Constructor for Begin events that takes a specific TimeStamp \a ts.
108  const Key& key,
109  TimeStamp ts,
110  TraceCategoryId cat) :
111  _key(key),
112  _category(cat),
113  _type(_InternalEventType::Begin),
114  _time(ts) {
115  }
116 
117  /// Constructor for End events that will automatically set the
118  /// timestamp from the current time.
119  TraceEvent(EndTag, const Key& key, TraceCategoryId cat) :
120  _key(key),
121  _category(cat),
122  _type(_InternalEventType::End),
123  _time(ArchGetTickTime()) {
124  }
125 
126  /// Constructor for End events that takes a specific TimeStamp \a ts.
128  const Key& key,
129  TimeStamp ts,
130  TraceCategoryId cat) :
131  _key(key),
132  _category(cat),
133  _type(_InternalEventType::End),
134  _time(ts) {
135  }
136 
137  /// Constructor for Timespan events that takes the start time and end time.
139  TimespanTag, const Key& key,
140  TimeStamp startTime, TimeStamp endTime,
141  TraceCategoryId cat) :
142  _key(key),
143  _category(cat),
144  _type(_InternalEventType::Timespan),
145  _time(endTime) {
146  new (&_payload) TimeStamp(startTime);
147  }
148 
149  /// Constructor for Marker events that will automatically set the
150  /// timestamp from the current time.
152  _key(key),
153  _category(cat),
154  _type(_InternalEventType::Marker),
155  _time(ArchGetTickTime()) {
156  }
157 
158  /// Constructor for Mark events that takes a specific TimeStamp \a ts.
160  const Key& key,
161  TimeStamp ts,
162  TraceCategoryId cat) :
163  _key(key),
164  _category(cat),
165  _type(_InternalEventType::Marker),
166  _time(ts) {
167  }
168 
169  /// Constructor for Counter delta events.
171  const Key& key,
172  double value,
173  TraceCategoryId cat) :
174  _key(key),
175  _category(cat),
176  _type(_InternalEventType::CounterDelta),
177  _time(ArchGetTickTime()) {
178  new (&_payload) double(value);
179  }
180 
181  /// Constructor for Counter value events.
183  const Key& key,
184  double value,
185  TraceCategoryId cat) :
186  _key(key),
187  _category(cat),
188  _type(_InternalEventType::CounterValue),
189  _time(ArchGetTickTime()) {
190  new (&_payload) double(value);
191  }
192 
193  /// \name Constructors for data events
194  /// @{
195  TraceEvent(DataTag, const Key& key, bool data, TraceCategoryId cat) :
196  _key(key),
197  _category(cat),
198  _dataType(DataType::Boolean),
199  _type(_InternalEventType::ScopeData),
200  _time(ArchGetTickTime()) {
201  new (&_payload) bool(data);
202  }
203 
204  TraceEvent(DataTag, const Key& key, int data, TraceCategoryId cat) :
205  _key(key),
206  _category(cat),
207  _dataType(DataType::Int),
208  _type(_InternalEventType::ScopeData),
209  _time(ArchGetTickTime()) {
210  new (&_payload) int64_t(data);
211  }
212 
213  TraceEvent(DataTag, const Key& key, int64_t data, TraceCategoryId cat) :
214  _key(key),
215  _category(cat),
216  _dataType(DataType::Int),
217  _type(_InternalEventType::ScopeData),
218  _time(ArchGetTickTime()) {
219  new (&_payload) int64_t(data);
220  }
221 
222  TraceEvent(DataTag, const Key& key, uint64_t data, TraceCategoryId cat) :
223  _key(key),
224  _category(cat),
225  _dataType(DataType::UInt),
226  _type(_InternalEventType::ScopeData),
227  _time(ArchGetTickTime()) {
228  new (&_payload) uint64_t(data);
229  }
230 
231  TraceEvent(DataTag, const Key& key, double data, TraceCategoryId cat) :
232  _key(key),
233  _category(cat),
234  _dataType(DataType::Float),
235  _type(_InternalEventType::ScopeData),
236  _time(ArchGetTickTime()) {
237  new (&_payload) double(data);
238  }
239 
240  TraceEvent(DataTag, const Key& key, const char* data, TraceCategoryId cat) :
241  _key(key),
242  _category(cat),
243  _dataType(DataType::String),
244  _type(_InternalEventType::ScopeDataLarge),
245  _time(ArchGetTickTime()) {
246  new (&_payload) const char*(data);
247  }
248  /// @}
249 
250  // Can move this, but not copy it
251  TraceEvent(const TraceEvent&) = delete;
252  TraceEvent& operator= (const TraceEvent&) = delete;
253 
254  TraceEvent(TraceEvent&&) = default;
255  TraceEvent& operator= (TraceEvent&&) = default;
256 
257  /// @}
258 
259  /// Sets the events timestamp to \p time.
260  void SetTimeStamp(TimeStamp time) { _time = time; }
261 private:
262  // Valid event types. This type has more detail that the public facing
263  // EventType enum.
264  enum class _InternalEventType : uint8_t {
265  Begin,
266  End,
267  Timespan,
268  Marker,
269  CounterDelta,
270  CounterValue,
271  ScopeData,
273  };
274 
275  using PayloadStorage = std::aligned_storage<8, 8>::type;
276 
277  Key _key;
278  TraceCategoryId _category;
279  DataType _dataType;
280  _InternalEventType _type;
281  TimeStamp _time;
282  PayloadStorage _payload;
283 };
284 
286 
287 #endif // PXR_BASE_TRACE_EVENT_H
The event represents an marker without a duration.
type
Definition: core.h:556
TraceEvent(EndTag, const Key &key, TimeStamp ts, TraceCategoryId cat)
Constructor for End events that takes a specific TimeStamp ts.
Definition: event.h:127
TraceEvent(DataTag, const Key &key, int64_t data, TraceCategoryId cat)
Definition: event.h:213
GT_API const UT_StringHolder time
The event is storing an double.
TraceEvent(MarkerTag, const Key &key, TraceCategoryId cat)
Definition: event.h:151
GLsizei const GLfloat * value
Definition: glcorearb.h:824
TraceEvent(DataTag, const Key &key, bool data, TraceCategoryId cat)
Definition: event.h:195
TRACE_API TraceEventData GetData() const
Returns the data stored in a data event.
CounterValueTag
Definition: event.h:43
The event is storing an unsigned integer.
The event is storing a bool.
TraceKey Key
Definition: event.h:34
TRACE_API EventType GetType() const
Returns the type of the event.
TraceEvent(EndTag, const Key &key, TraceCategoryId cat)
Definition: event.h:119
TRACE_API double GetCounterValue() const
Return the counter value associated with this event.
MarkerTag
Definition: event.h:41
The event represents the ending timestamp of a scope.
TraceEvent(CounterValueTag, const Key &key, double value, TraceCategoryId cat)
Constructor for Counter value events.
Definition: event.h:182
TRACE_API TimeStamp GetStartTimeStamp() const
Returns the start time of a timespan event.
TraceEvent(DataTag, const Key &key, int data, TraceCategoryId cat)
Definition: event.h:204
The event is storing a string.
TraceEvent(TimespanTag, const Key &key, TimeStamp startTime, TimeStamp endTime, TraceCategoryId cat)
Constructor for Timespan events that takes the start time and end time.
Definition: event.h:138
TraceEvent(BeginTag, const Key &key, TraceCategoryId cat)
Definition: event.h:99
TRACE_API TimeStamp GetEndTimeStamp() const
Returns the end time of a timespan event.
TimespanTag
Definition: event.h:40
TraceEvent & operator=(const TraceEvent &)=delete
The event is storing an integer.
TraceEvent(CounterDeltaTag, const Key &key, double value, TraceCategoryId cat)
Constructor for Counter delta events.
Definition: event.h:170
PXR_NAMESPACE_OPEN_SCOPE uint64_t ArchGetTickTime()
Definition: timing.h:45
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
The event is not storing any data.
The event represents the beginning timestamp of a scope.
TraceEvent(DataTag, const Key &key, double data, TraceCategoryId cat)
Definition: event.h:231
DataType
The different types of data that can be stored in a TraceEvent instance.
Definition: event.h:61
BeginTag
Definition: event.h:38
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
uint64_t TimeStamp
Time in "ticks".
Definition: event.h:33
The event is an unknown type.
const Key & GetKey() const
Return this event's key.
Definition: event.h:71
EventType
Valid event types.
Definition: event.h:48
The event stores data that is associated with its enclosing scope.
TRACE_API TimeStamp GetTimeStamp() const
Return the time stamp associated with this event.
TraceEvent(MarkerTag, const Key &key, TimeStamp ts, TraceCategoryId cat)
Constructor for Mark events that takes a specific TimeStamp ts.
Definition: event.h:159
TraceEvent(BeginTag, const Key &key, TimeStamp ts, TraceCategoryId cat)
Constructor for Begin events that takes a specific TimeStamp ts.
Definition: event.h:107
The event represents a change in a counter.
CounterDeltaTag
Definition: event.h:42
uint32_t TraceCategoryId
Categories that a TraceReporter can use to filter events.
Definition: category.h:27
The event represents begin and end timestamp of a scope.
void SetTimeStamp(TimeStamp time)
Sets the events timestamp to time.
Definition: event.h:260
Definition: format.h:1821
TraceEvent(DataTag, const Key &key, const char *data, TraceCategoryId cat)
Definition: event.h:240
The event represents the value of a counter.
#define TRACE_API
Definition: api.h:23
Definition: key.h:23
TraceCategoryId GetCategory() const
Returns the event's category id.
Definition: event.h:80
TraceEvent(DataTag, const Key &key, uint64_t data, TraceCategoryId cat)
Definition: event.h:222