include/babeltrace2/trace-ir/event.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_TRACE_IR_EVENT_H
   8 #define BABELTRACE2_TRACE_IR_EVENT_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-tir-ev Event
  24 @ingroup api-tir
  25
  26 @brief
  27     Trace event.
  28
  29 An <strong><em>event</em></strong> represents a trace event record.
  30
  31 An event is an instance of an \bt_ev_cls:
  32
  33 @image html trace-structure.png
  34
  35 In the illustration above, notice that:
  36
  37 - A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
  38   some of which are \bt_p_ev_msg.
  39 - An event message contains an \bt_ev.
  40 - An event is an instance of an event class.
  41 - The \ref api-tir-ev-prop-payload "payload field" of an event is an
  42   instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
  43   which an event class contains.
  44
  45 Borrow the class of an event with bt_event_borrow_class() and
  46 bt_event_borrow_class_const().
  47
  48 An event is a \ref api-tir "trace IR" data object.
  49
  50 You cannot directly create an event: there's no
  51 <code>bt_event_create()</code> function. The \bt_name library
  52 creates an event within an \bt_ev_msg from an \bt_ev_cls.
  53 Therefore, to fill the fields of an event, you must first
  54 borrow the event from an event message with
  55 bt_message_event_borrow_event().
  56
  57 An event is a \ref api-fund-unique-object "unique object": it belongs to
  58 an \bt_ev_msg.
  59
  60 Some library functions \ref api-fund-freezing "freeze" events on
  61 success. The documentation of those functions indicate this
  62 postcondition.
  63
  64 The type of an event is #bt_event.
  65
  66 An event conceptually belongs to a \bt_stream. Borrow the stream of an
  67 event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
  68
  69 If the event's stream's class
  70 \ref api-tir-stream-cls-prop-supports-pkt "supports packets",
  71 the event also belongs to a \bt_pkt. In that case, borrow the packet of
  72 an event with bt_event_borrow_packet() and
  73 bt_event_borrow_packet_const().
  74
  75 Because a stream or a packet could contain millions of events, there are
  76 no actual links from a stream or from a packet to its events.
  77
  78 <h1>Properties</h1>
  79
  80 An event has the following properties:
  81
  82 <dl>
  83   <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
  84   <dd>
  85     Event's payload \bt_field.
  86
  87     The payload of an event contains its main trace data.
  88
  89     The \ref api-tir-fc "class" of an event's payload field is set
  90     at the event's \ref api-tir-ev-cls "class" level. See
  91     bt_event_class_set_payload_field_class(),
  92     bt_event_class_borrow_payload_field_class(), and
  93     bt_event_class_borrow_payload_field_class_const().
  94
  95     Use bt_event_borrow_payload_field() and
  96     bt_event_borrow_payload_field_const().
  97   </dd>
  98
  99   <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
 100   <dd>
 101     Event's specific context \bt_field.
 102
 103     The specific context of an event contains
 104     any contextual data of which the layout is specific to the
 105     event's \ref api-tir-ev-cls "class" and which does not belong to the
 106     payload.
 107
 108     The \ref api-tir-fc "class" of an event's specific context field is
 109     set at the event's \ref api-tir-ev-cls "class" level. See
 110     bt_event_class_set_specific_context_field_class()
 111     bt_event_class_borrow_specific_context_field_class(),
 112     and bt_event_class_borrow_specific_context_field_class_const()
 113
 114     Use bt_event_borrow_specific_context_field() and
 115     bt_event_borrow_specific_context_field_const().
 116   </dd>
 117
 118   <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
 119   <dd>
 120     Event's common context \bt_field.
 121
 122     The common context of an event contains contextual data of which the
 123     layout is common to all the \bt_p_ev_cls of the
 124     event's stream's \ref api-tir-stream-cls "class".
 125
 126     The \ref api-tir-fc "class" of an event's common context field is set
 127     at the event's \bt_stream_cls level. See
 128     bt_stream_class_set_event_common_context_field_class()
 129     bt_stream_class_borrow_event_common_context_field_class(),
 130     and bt_stream_class_borrow_event_common_context_field_class_const().
 131
 132     Use bt_event_borrow_common_context_field() and
 133     bt_event_borrow_common_context_field_const().
 134   </dd>
 135 </dl>
 136 */
 137
 138 /*! @{ */
 139
 140 /*!
 141 @name Type
 142 @{
 143
 144 @typedef struct bt_event bt_event;
 145
 146 @brief
 147     Event.
 148
 149 @}
 150 */
 151
 152 /*!
 153 @name Class access
 154 @{
 155 */
 156
 157 /*!
 158 @brief
 159     Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
 160
 161 @param[in] event
 162     Event of which to borrow the class.
 163
 164 @returns
 165     \em Borrowed reference of the class of \bt_p{event}.
 166
 167 @bt_pre_not_null{event}
 168
 169 @sa bt_event_borrow_class_const() &mdash;
 170     \c const version of this function.
 171 */
 172 extern bt_event_class *bt_event_borrow_class(bt_event *event) __BT_NOEXCEPT;
 173
 174 /*!
 175 @brief
 176     Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
 177     (\c const version).
 178
 179 See bt_event_borrow_class().
 180 */
 181 extern const bt_event_class *bt_event_borrow_class_const(
 182                 const bt_event *event) __BT_NOEXCEPT;
 183
 184 /*! @} */
 185
 186 /*!
 187 @name Stream access
 188 @{
 189 */
 190
 191 /*!
 192 @brief
 193     Borrows the \bt_stream conceptually containing the event
 194     \bt_p{event}.
 195
 196 @param[in] event
 197     Event of which to borrow the stream conceptually containing it.
 198
 199 @returns
 200     \em Borrowed reference of the stream conceptually containing
 201     \bt_p{event}.
 202
 203 @bt_pre_not_null{event}
 204
 205 @sa bt_event_borrow_stream_const() &mdash;
 206     \c const version of this function.
 207 */
 208 extern bt_stream *bt_event_borrow_stream(bt_event *event) __BT_NOEXCEPT;
 209
 210 /*!
 211 @brief
 212     Borrows the \bt_stream conceptually containing the event
 213     \bt_p{event} (\c const version).
 214
 215 See bt_event_borrow_stream().
 216 */
 217 extern const bt_stream *bt_event_borrow_stream_const(
 218                 const bt_event *event) __BT_NOEXCEPT;
 219
 220 /*! @} */
 221
 222 /*!
 223 @name Packet access
 224 @{
 225 */
 226
 227 /*!
 228 @brief
 229     Borrows the \bt_pkt conceptually containing the event
 230     \bt_p{event}.
 231
 232 @attention
 233     Only call this function if bt_stream_class_supports_packets()
 234     returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
 235
 236 @param[in] event
 237     Event of which to borrow the packet conceptually containing it.
 238
 239 @returns
 240     \em Borrowed reference of the packet conceptually containing
 241     \bt_p{event}.
 242
 243 @bt_pre_not_null{event}
 244
 245 @sa bt_event_borrow_packet_const() &mdash;
 246     \c const version of this function.
 247 */
 248 extern bt_packet *bt_event_borrow_packet(bt_event *event) __BT_NOEXCEPT;
 249
 250 /*!
 251 @brief
 252     Borrows the \bt_pkt conceptually containing the event
 253     \bt_p{event} (\c const version).
 254
 255 See bt_event_borrow_packet().
 256 */
 257 extern const bt_packet *bt_event_borrow_packet_const(
 258                 const bt_event *event) __BT_NOEXCEPT;
 259
 260 /*! @} */
 261
 262 /*!
 263 @name Properties
 264 @{
 265 */
 266
 267 /*!
 268 @brief
 269     Borrows the payload \bt_field of the event \bt_p{event}.
 270
 271 See the \ref api-tir-ev-prop-payload "payload field" property.
 272
 273 @param[in] event
 274     Event of which to borrow the payload field.
 275
 276 @returns
 277     \em Borrowed reference of the payload field of \bt_p{event},
 278     or \c NULL if none.
 279
 280 @bt_pre_not_null{event}
 281
 282 @sa bt_event_borrow_payload_field_const() &mdash;
 283     \c const version of this function.
 284 */
 285 extern bt_field *bt_event_borrow_payload_field(bt_event *event) __BT_NOEXCEPT;
 286
 287 /*!
 288 @brief
 289     Borrows the payload \bt_field of the event \bt_p{event}
 290     (\c const version).
 291
 292 See bt_event_borrow_payload_field().
 293 */
 294 extern const bt_field *bt_event_borrow_payload_field_const(
 295                 const bt_event *event) __BT_NOEXCEPT;
 296
 297 /*!
 298 @brief
 299     Borrows the specific context \bt_field of the event \bt_p{event}.
 300
 301 See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
 302
 303 @param[in] event
 304     Event of which to borrow the specific context field.
 305
 306 @returns
 307     \em Borrowed reference of the specific context field of
 308     \bt_p{event}, or \c NULL if none.
 309
 310 @bt_pre_not_null{event}
 311
 312 @sa bt_event_borrow_specific_context_field_const() &mdash;
 313     \c const version of this function.
 314 */
 315 extern bt_field *
 316 bt_event_borrow_specific_context_field(bt_event *event) __BT_NOEXCEPT;
 317
 318 /*!
 319 @brief
 320     Borrows the specific context \bt_field of the event \bt_p{event}
 321     (\c const version).
 322
 323 See bt_event_borrow_specific_context_field().
 324 */
 325 extern const bt_field *bt_event_borrow_specific_context_field_const(
 326                 const bt_event *event) __BT_NOEXCEPT;
 327
 328 /*!
 329 @brief
 330     Borrows the common context \bt_field of the event \bt_p{event}.
 331
 332 See the \ref api-tir-ev-prop-common-ctx "common context field" property.
 333
 334 @param[in] event
 335     Event of which to borrow the common context field.
 336
 337 @returns
 338     \em Borrowed reference of the common context field of
 339     \bt_p{event}, or \c NULL if none.
 340
 341 @bt_pre_not_null{event}
 342
 343 @sa bt_event_borrow_specific_context_field_const() &mdash;
 344     \c const version of this function.
 345 */
 346 extern bt_field *
 347 bt_event_borrow_common_context_field(bt_event *event) __BT_NOEXCEPT;
 348
 349 /*!
 350 @brief
 351     Borrows the common context \bt_field of the event \bt_p{event}
 352     (\c const version).
 353
 354 See bt_event_borrow_common_context_field().
 355 */
 356 extern const bt_field *bt_event_borrow_common_context_field_const(
 357                 const bt_event *event) __BT_NOEXCEPT;
 358
 359 /*! @} */
 360
 361 /*! @} */
 362
 363 #ifdef __cplusplus
 364 }
 365 #endif
 366
 367 #endif /* BABELTRACE2_TRACE_IR_EVENT_H */