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 Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 
25 #ifndef PXR_BASE_TRACE_EVENT_H
26 #define PXR_BASE_TRACE_EVENT_H
27 
28 #include "pxr/pxr.h"
29 
30 #include "pxr/base/trace/api.h"
32 #include "pxr/base/trace/key.h"
33 
34 #include "pxr/base/arch/timing.h"
35 
37 
38 class TraceEventData;
39 
40 ////////////////////////////////////////////////////////////////////////////////
41 /// \class TraceEvent
42 ///
43 /// This represents an event recorded by a TraceCollector.
44 /// It contains a key (name), categoryId, timestamp, type, and optional
45 /// metadata.
46 ///
47 class TraceEvent {
48 public:
49  /// Time in "ticks".
50  using TimeStamp = uint64_t;
51  using Key = TraceKey;
52 
53  /// \name Tag enums to select constructors
54  /// @{
55  enum BeginTag { Begin };
56  enum EndTag { End };
58  enum MarkerTag { Marker };
61  enum DataTag { Data };
62  /// @}
63 
64  /// Valid event types
65  enum class EventType : uint8_t {
66  Unknown, ///< The event is an unknown type.
67  Begin, ///< The event represents the beginning timestamp of a scope.
68  End, ///< The event represents the ending timestamp of a scope.
69  Timespan, ///< The event represents begin and end timestamp of a scope.
70  Marker, ///< The event represents an marker without a duration.
71  CounterDelta, ///< The event represents a change in a counter.
72  CounterValue, ///< The event represents the value of a counter.
73  ScopeData,
74  ///< The event stores data that is associated with its enclosing scope.
75  };
76 
77  /// The different types of data that can be stored in a TraceEvent instance.
78  enum class DataType : uint8_t {
79  String, ///< The event is storing a string.
80  Boolean, ///< The event is storing a bool.
81  Int, ///< The event is storing an integer.
82  UInt, ///< The event is storing an unsigned integer.
83  Float, ///< The event is storing an double.
84  Invalid ///< The event is not storing any data.
85  };
86 
87  /// Return this event's key.
88  const Key& GetKey() const { return _key; }
89 
90  /// Return the time stamp associated with this event.
92 
93  /// Return the counter value associated with this event.
94  TRACE_API double GetCounterValue() const;
95 
96  /// Returns the event's category id.
97  TraceCategoryId GetCategory() const { return _category; }
98 
99  /// Returns the start time of a timespan event.
101 
102  /// Returns the end time of a timespan event.
104 
105  /// Returns the data stored in a data event.
107 
108  /// Returns the type of the event.
109  TRACE_API EventType GetType() const;
110 
111  /// \name Constructors
112  /// @{
113 
114  /// Constructor for Begin events that will automatically set the
115  /// timestamp from the current time.
117  _key(key),
118  _category(cat),
119  _type(_InternalEventType::Begin),
120  _time(ArchGetTickTime()) {
121  }
122 
123  /// Constructor for Begin events that takes a specific TimeStamp \a ts.
125  const Key& key,
126  TimeStamp ts,
127  TraceCategoryId cat) :
128  _key(key),
129  _category(cat),
130  _type(_InternalEventType::Begin),
131  _time(ts) {
132  }
133 
134  /// Constructor for End events that will automatically set the
135  /// timestamp from the current time.
136  TraceEvent(EndTag, const Key& key, TraceCategoryId cat) :
137  _key(key),
138  _category(cat),
139  _type(_InternalEventType::End),
140  _time(ArchGetTickTime()) {
141  }
142 
143  /// Constructor for End events that takes a specific TimeStamp \a ts.
145  const Key& key,
146  TimeStamp ts,
147  TraceCategoryId cat) :
148  _key(key),
149  _category(cat),
150  _type(_InternalEventType::End),
151  _time(ts) {
152  }
153 
154  /// Constructor for Timespan events that takes a TimeStamp \a starttime
155  /// and automatically sets the end timestamp from the current time.
157  TimespanTag, const Key& key, TimeStamp startTime, TraceCategoryId cat) :
158  _key(key),
159  _category(cat),
160  _type(_InternalEventType::Timespan),
161  _time(ArchGetTickTime()) {
162  new (&_payload) TimeStamp(startTime);
163  }
164 
165  /// Constructor for Timespan events that takes the start time and end time.
167  TimespanTag, const Key& key,
168  TimeStamp startTime, TimeStamp endTime,
169  TraceCategoryId cat) :
170  _key(key),
171  _category(cat),
172  _type(_InternalEventType::Timespan),
173  _time(endTime) {
174  new (&_payload) TimeStamp(startTime);
175  }
176 
177  /// Constructor for Marker events that will automatically set the
178  /// timestamp from the current time.
180  _key(key),
181  _category(cat),
182  _type(_InternalEventType::Marker),
183  _time(ArchGetTickTime()) {
184  }
185 
186  /// Constructor for Mark events that takes a specific TimeStamp \a ts.
188  const Key& key,
189  TimeStamp ts,
190  TraceCategoryId cat) :
191  _key(key),
192  _category(cat),
193  _type(_InternalEventType::Marker),
194  _time(ts) {
195  }
196 
197  /// Constructor for Counter delta events.
199  const Key& key,
200  double value,
201  TraceCategoryId cat) :
202  _key(key),
203  _category(cat),
204  _type(_InternalEventType::CounterDelta),
205  _time(ArchGetTickTime()) {
206  new (&_payload) double(value);
207  }
208 
209  /// Constructor for Counter value events.
211  const Key& key,
212  double value,
213  TraceCategoryId cat) :
214  _key(key),
215  _category(cat),
216  _type(_InternalEventType::CounterValue),
217  _time(ArchGetTickTime()) {
218  new (&_payload) double(value);
219  }
220 
221  /// \name Constructors for data events
222  /// @{
223  TraceEvent(DataTag, const Key& key, bool data, TraceCategoryId cat) :
224  _key(key),
225  _category(cat),
226  _dataType(DataType::Boolean),
227  _type(_InternalEventType::ScopeData),
228  _time(ArchGetTickTime()) {
229  new (&_payload) bool(data);
230  }
231 
232  TraceEvent(DataTag, const Key& key, int data, TraceCategoryId cat) :
233  _key(key),
234  _category(cat),
235  _dataType(DataType::Int),
236  _type(_InternalEventType::ScopeData),
237  _time(ArchGetTickTime()) {
238  new (&_payload) int64_t(data);
239  }
240 
241  TraceEvent(DataTag, const Key& key, int64_t data, TraceCategoryId cat) :
242  _key(key),
243  _category(cat),
244  _dataType(DataType::Int),
245  _type(_InternalEventType::ScopeData),
246  _time(ArchGetTickTime()) {
247  new (&_payload) int64_t(data);
248  }
249 
250  TraceEvent(DataTag, const Key& key, uint64_t data, TraceCategoryId cat) :
251  _key(key),
252  _category(cat),
253  _dataType(DataType::UInt),
254  _type(_InternalEventType::ScopeData),
255  _time(ArchGetTickTime()) {
256  new (&_payload) uint64_t(data);
257  }
258 
259  TraceEvent(DataTag, const Key& key, double data, TraceCategoryId cat) :
260  _key(key),
261  _category(cat),
262  _dataType(DataType::Float),
263  _type(_InternalEventType::ScopeData),
264  _time(ArchGetTickTime()) {
265  new (&_payload) double(data);
266  }
267 
268  TraceEvent(DataTag, const Key& key, const char* data, TraceCategoryId cat) :
269  _key(key),
270  _category(cat),
271  _dataType(DataType::String),
272  _type(_InternalEventType::ScopeDataLarge),
273  _time(ArchGetTickTime()) {
274  new (&_payload) const char*(data);
275  }
276  /// @}
277 
278  // Can move this, but not copy it
279  TraceEvent(const TraceEvent&) = delete;
280  TraceEvent& operator= (const TraceEvent&) = delete;
281 
282  TraceEvent(TraceEvent&&) = default;
283  TraceEvent& operator= (TraceEvent&&) = default;
284 
285  /// @}
286 
287  /// Sets the events timestamp to \p time.
288  void SetTimeStamp(TimeStamp time) { _time = time; }
289 private:
290  // Valid event types. This type has more detail that the public facing
291  // EventType enum.
292  enum class _InternalEventType : uint8_t {
293  Begin,
294  End,
295  Timespan,
296  Marker,
297  CounterDelta,
298  CounterValue,
299  ScopeData,
301  };
302 
303  using PayloadStorage = std::aligned_storage<8, 8>::type;
304 
305  Key _key;
306  TraceCategoryId _category;
307  DataType _dataType;
308  _InternalEventType _type;
309  TimeStamp _time;
310  PayloadStorage _payload;
311 };
312 
314 
315 #endif // PXR_BASE_TRACE_EVENT_H
The event represents an marker without a duration.
TraceEvent(EndTag, const Key &key, TimeStamp ts, TraceCategoryId cat)
Constructor for End events that takes a specific TimeStamp ts.
Definition: event.h:144
TraceEvent(DataTag, const Key &key, int64_t data, TraceCategoryId cat)
Definition: event.h:241
GT_API const UT_StringHolder time
The event is storing an double.
TraceEvent(MarkerTag, const Key &key, TraceCategoryId cat)
Definition: event.h:179
uint64_t ArchGetTickTime()
Definition: timing.h:64
TraceEvent(DataTag, const Key &key, bool data, TraceCategoryId cat)
Definition: event.h:223
TRACE_API TraceEventData GetData() const
Returns the data stored in a data event.
CounterValueTag
Definition: event.h:60
The event is storing an unsigned integer.
The event is storing a bool.
TraceKey Key
Definition: event.h:51
TRACE_API EventType GetType() const
Returns the type of the event.
TraceEvent(EndTag, const Key &key, TraceCategoryId cat)
Definition: event.h:136
TRACE_API double GetCounterValue() const
Return the counter value associated with this event.
MarkerTag
Definition: event.h:58
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:210
TRACE_API TimeStamp GetStartTimeStamp() const
Returns the start time of a timespan event.
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
TraceEvent(DataTag, const Key &key, int data, TraceCategoryId cat)
Definition: event.h:232
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:166
TraceEvent(BeginTag, const Key &key, TraceCategoryId cat)
Definition: event.h:116
TRACE_API TimeStamp GetEndTimeStamp() const
Returns the end time of a timespan event.
TimespanTag
Definition: event.h:57
TraceEvent & operator=(const TraceEvent &)=delete
TraceEvent(TimespanTag, const Key &key, TimeStamp startTime, TraceCategoryId cat)
Definition: event.h:156
The event is storing an integer.
TraceEvent(CounterDeltaTag, const Key &key, double value, TraceCategoryId cat)
Constructor for Counter delta events.
Definition: event.h:198
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
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:259
DataType
The different types of data that can be stored in a TraceEvent instance.
Definition: event.h:78
BeginTag
Definition: event.h:55
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
uint64_t TimeStamp
Time in "ticks".
Definition: event.h:50
The event is an unknown type.
const Key & GetKey() const
Return this event's key.
Definition: event.h:88
EventType
Valid event types.
Definition: event.h:65
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:187
TraceEvent(BeginTag, const Key &key, TimeStamp ts, TraceCategoryId cat)
Constructor for Begin events that takes a specific TimeStamp ts.
Definition: event.h:124
The event represents a change in a counter.
CounterDeltaTag
Definition: event.h:59
uint32_t TraceCategoryId
Categories that a TraceReporter can use to filter events.
Definition: category.h:44
GLsizei const GLfloat * value
Definition: glew.h:1849
The event represents begin and end timestamp of a scope.
void SetTimeStamp(TimeStamp time)
Sets the events timestamp to time.
Definition: event.h:288
TraceEvent(DataTag, const Key &key, const char *data, TraceCategoryId cat)
Definition: event.h:268
type
Definition: core.h:528
The event represents the value of a counter.
#define TRACE_API
Definition: api.h:40
Definition: key.h:40
TraceCategoryId GetCategory() const
Returns the event's category id.
Definition: event.h:97
TraceEvent(DataTag, const Key &key, uint64_t data, TraceCategoryId cat)
Definition: event.h:250