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