include/babeltrace2/trace-ir/event.h

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