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 the start time and end time.
156  TimespanTag, const Key& key,
157  TimeStamp startTime, TimeStamp endTime,
158  TraceCategoryId cat) :
159  _key(key),
160  _category(cat),
161  _type(_InternalEventType::Timespan),
162  _time(endTime) {
163  new (&_payload) TimeStamp(startTime);
164  }
165 
166  /// Constructor for Marker events that will automatically set the
167  /// timestamp from the current time.
169  _key(key),
170  _category(cat),
171  _type(_InternalEventType::Marker),
172  _time(ArchGetTickTime()) {
173  }
174 
175  /// Constructor for Mark events that takes a specific TimeStamp \a ts.
177  const Key& key,
178  TimeStamp ts,
179  TraceCategoryId cat) :
180  _key(key),
181  _category(cat),
182  _type(_InternalEventType::Marker),
183  _time(ts) {
184  }
185 
186  /// Constructor for Counter delta events.
188  const Key& key,
189  double value,
190  TraceCategoryId cat) :
191  _key(key),
192  _category(cat),
193  _type(_InternalEventType::CounterDelta),
194  _time(ArchGetTickTime()) {
195  new (&_payload) double(value);
196  }
197 
198  /// Constructor for Counter value events.
200  const Key& key,
201  double value,
202  TraceCategoryId cat) :
203  _key(key),
204  _category(cat),
205  _type(_InternalEventType::CounterValue),
206  _time(ArchGetTickTime()) {
207  new (&_payload) double(value);
208  }
209 
210  /// \name Constructors for data events
211  /// @{
212  TraceEvent(DataTag, const Key& key, bool data, TraceCategoryId cat) :
213  _key(key),
214  _category(cat),
215  _dataType(DataType::Boolean),
216  _type(_InternalEventType::ScopeData),
217  _time(ArchGetTickTime()) {
218  new (&_payload) bool(data);
219  }
220 
221  TraceEvent(DataTag, const Key& key, int data, TraceCategoryId cat) :
222  _key(key),
223  _category(cat),
224  _dataType(DataType::Int),
225  _type(_InternalEventType::ScopeData),
226  _time(ArchGetTickTime()) {
227  new (&_payload) int64_t(data);
228  }
229 
230  TraceEvent(DataTag, const Key& key, int64_t data, TraceCategoryId cat) :
231  _key(key),
232  _category(cat),
233  _dataType(DataType::Int),
234  _type(_InternalEventType::ScopeData),
235  _time(ArchGetTickTime()) {
236  new (&_payload) int64_t(data);
237  }
238 
239  TraceEvent(DataTag, const Key& key, uint64_t data, TraceCategoryId cat) :
240  _key(key),
241  _category(cat),
242  _dataType(DataType::UInt),
243  _type(_InternalEventType::ScopeData),
244  _time(ArchGetTickTime()) {
245  new (&_payload) uint64_t(data);
246  }
247 
248  TraceEvent(DataTag, const Key& key, double data, TraceCategoryId cat) :
249  _key(key),
250  _category(cat),
251  _dataType(DataType::Float),
252  _type(_InternalEventType::ScopeData),
253  _time(ArchGetTickTime()) {
254  new (&_payload) double(data);
255  }
256 
257  TraceEvent(DataTag, const Key& key, const char* data, TraceCategoryId cat) :
258  _key(key),
259  _category(cat),
260  _dataType(DataType::String),
261  _type(_InternalEventType::ScopeDataLarge),
262  _time(ArchGetTickTime()) {
263  new (&_payload) const char*(data);
264  }
265  /// @}
266 
267  // Can move this, but not copy it
268  TraceEvent(const TraceEvent&) = delete;
269  TraceEvent& operator= (const TraceEvent&) = delete;
270 
271  TraceEvent(TraceEvent&&) = default;
272  TraceEvent& operator= (TraceEvent&&) = default;
273 
274  /// @}
275 
276  /// Sets the events timestamp to \p time.
277  void SetTimeStamp(TimeStamp time) { _time = time; }
278 private:
279  // Valid event types. This type has more detail that the public facing
280  // EventType enum.
281  enum class _InternalEventType : uint8_t {
282  Begin,
283  End,
284  Timespan,
285  Marker,
286  CounterDelta,
287  CounterValue,
288  ScopeData,
290  };
291 
292  using PayloadStorage = std::aligned_storage<8, 8>::type;
293 
294  Key _key;
295  TraceCategoryId _category;
296  DataType _dataType;
297  _InternalEventType _type;
298  TimeStamp _time;
299  PayloadStorage _payload;
300 };
301 
303 
304 #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:230
GT_API const UT_StringHolder time
The event is storing an double.
TraceEvent(MarkerTag, const Key &key, TraceCategoryId cat)
Definition: event.h:168
TraceEvent(DataTag, const Key &key, bool data, TraceCategoryId cat)
Definition: event.h:212
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:199
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:221
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:155
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
The event is storing an integer.
TraceEvent(CounterDeltaTag, const Key &key, double value, TraceCategoryId cat)
Constructor for Counter delta events.
Definition: event.h:187
PXR_NAMESPACE_OPEN_SCOPE uint64_t ArchGetTickTime()
Definition: timing.h:62
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
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:248
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
Definition: core.h:1131
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:176
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
type
Definition: core.h:1059
The event represents begin and end timestamp of a scope.
void SetTimeStamp(TimeStamp time)
Sets the events timestamp to time.
Definition: event.h:277
Definition: format.h:895
TraceEvent(DataTag, const Key &key, const char *data, TraceCategoryId cat)
Definition: event.h:257
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:239