include/babeltrace/ctf-ir/event.h

   1 #ifndef BABELTRACE_CTF_IR_EVENT_H
   2 #define BABELTRACE_CTF_IR_EVENT_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 /* For bt_get() */
  34 #include <babeltrace/ref.h>
  35
  36 #include <stdint.h>
  37 #include <stddef.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 struct bt_value;
  44 struct bt_clock_class;
  45
  46 /**
  47 @defgroup ctfirevent CTF IR event
  48 @ingroup ctfir
  49 @brief CTF IR event.
  50
  51 @code
  52 #include <babeltrace/ctf-ir/event.h>
  53 @endcode
  54
  55 A CTF IR <strong><em>event</em></strong> is a container of event
  56 fields:
  57
  58 - <strong>Stream event header</strong> field, described by the
  59   <em>stream event header field type</em> of a
  60   \link ctfirstreamclass CTF IR stream class\endlink.
  61 - <strong>Stream event context</strong> field, described by the
  62   <em>stream event context field type</em> of a stream class.
  63 - <strong>Event context</strong> field, described by the
  64   <em>event context field type</em> of a
  65   \link ctfireventclass CTF IR event class\endlink.
  66 - <strong>Event payload</strong>, described by the
  67   <em>event payload field type</em> of an event class.
  68
  69 As a reminder, here's the structure of a CTF packet:
  70
  71 @imgpacketstructure
  72
  73 You can create a CTF IR event \em from a
  74 \link ctfireventclass CTF IR event class\endlink with
  75 bt_event_create(). The event class you use to create an event
  76 object becomes its parent.
  77
  78 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
  79 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
  80 which is the parent of its event class) was created by a
  81 \link ctfwriter CTF writer\endlink object, then the only possible
  82 action you can do with this event object is to append it to a
  83 \link ctfirstream CTF IR stream\endlink with
  84 bt_stream_append_event(). Otherwise, you can create an event
  85 notification with bt_notification_event_create(). The event you pass
  86 to this function \em must have an attached packet object first.
  87
  88 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
  89 event object with bt_event_set_packet().
  90
  91 A CTF IR event has a mapping of
  92 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
  93 an instance of a specific
  94 \link ctfirclockclass CTF IR clock class\endlink when the event is
  95 emitted. You can set an event object's clock value with
  96 bt_event_set_clock_value().
  97
  98 As with any Babeltrace object, CTF IR event objects have
  99 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 100 counts</a>. See \ref refs to learn more about the reference counting
 101 management of Babeltrace objects.
 102
 103 bt_notification_event_create() \em freezes its event parameter on
 104 success. You cannot modify a frozen event object: it is considered
 105 immutable, except for \link refs reference counting\endlink.
 106
 107 @sa ctfireventclass
 108 @sa ctfirpacket
 109
 110 @file
 111 @brief CTF IR event type and functions.
 112 @sa ctfirevent
 113
 114 @addtogroup ctfirevent
 115 @{
 116 */
 117
 118 /**
 119 @struct bt_event
 120 @brief A CTF IR event.
 121 @sa ctfirevent
 122 */
 123 struct bt_event;
 124 struct bt_clock;
 125 struct bt_clock_value;
 126 struct bt_event_class;
 127 struct bt_field;
 128 struct bt_field_type;
 129 struct bt_stream_class;
 130 struct bt_packet;
 131
 132 /**
 133 @name Creation and parent access functions
 134 @{
 135 */
 136
 137 /**
 138 @brief  Creates a default CTF IR event from the CTF IR event class
 139         \p event_class.
 140
 141 \p event_class \em must have a parent
 142 \link ctfirstreamclass CTF IR stream class\endlink.
 143
 144 On success, the four fields of the created event object are not set. You
 145 can set them with bt_event_set_header(),
 146 bt_event_set_stream_event_context(),
 147 bt_event_set_context(), and bt_event_set_payload().
 148
 149 This function tries to resolve the needed
 150 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 151 types that are found anywhere in the context or payload field
 152 types of \p event_class and in the root field types of the
 153 parent stream class of \p event_class. If any automatic resolving fails,
 154 this function fails. This means that, if any dynamic field type need
 155 a field type which should be found in the trace packet header root
 156 field type, and if the parent stream class of \p event_class was not
 157 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
 158 with bt_trace_add_stream_class(), then this function fails.
 159
 160 @param[in] event_class  CTF IR event class to use to create the
 161                         CTF IR event.
 162 @returns                Created event object, or \c NULL on error.
 163
 164 @prenotnull{event_class}
 165 @pre \p event_class has a parent stream class.
 166 @postsuccessrefcountret1
 167 */
 168 extern struct bt_event *bt_event_create(struct bt_event_class *event_class);
 169
 170 extern struct bt_event_class *bt_event_borrow_class(struct bt_event *event);
 171
 172 /**
 173 @brief  Returns the parent CTF IR event class of the CTF IR event
 174         \p event.
 175
 176 This function returns a reference to the event class which was used to
 177 create the event object in the first place with bt_event_create().
 178
 179 @param[in] event        Event of which to get the parent event class.
 180 @returns                Parent event class of \p event,
 181                         or \c NULL on error.
 182
 183 @prenotnull{event}
 184 @postrefcountsame{event}
 185 @postsuccessrefcountretinc
 186 */
 187 static inline
 188 struct bt_event_class *bt_event_get_class(struct bt_event *event)
 189 {
 190         return bt_get(bt_event_borrow_class(event));
 191 }
 192
 193 extern struct bt_packet *bt_event_borrow_packet(struct bt_event *event);
 194
 195 /**
 196 @brief  Returns the CTF IR packet associated to the CTF IR event
 197         \p event.
 198
 199 This function returns a reference to the event class which was set to
 200 \p event in the first place with bt_event_set_packet().
 201
 202 @param[in] event        Event of which to get the associated packet.
 203 @returns                Packet associated to \p event,
 204                         or \c NULL if no packet is associated to
 205                         \p event or on error.
 206
 207 @prenotnull{event}
 208 @postrefcountsame{event}
 209 @postsuccessrefcountretinc
 210
 211 @sa bt_event_set_packet(): Associates a given event to a given
 212         packet.
 213 */
 214 static inline
 215 struct bt_packet *bt_event_get_packet(struct bt_event *event)
 216 {
 217         return bt_get(bt_event_borrow_packet(event));
 218 }
 219
 220 /**
 221 @brief  Associates the CTF IR event \p event to the CTF IR packet
 222         \p packet.
 223
 224 The \link ctfirstreamclass CTF IR stream class\endlink of the
 225 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
 226 be the same as the parent stream class of the
 227 \link ctfireventclass CTF IR event class\endlink returned
 228 by bt_event_get_class() for \p event.
 229
 230 You \em must call this function to create an event-packet association
 231 before you call bt_notification_event_create() with \p event.
 232
 233 On success, this function also sets the parent stream object of
 234 \p event to the parent stream of \p packet.
 235
 236 @param[in] event        Event to which to associate \p packet.
 237 @param[in] packet       Packet to associate to \p event.
 238 @returns                0 on success, or a negative value on error.
 239
 240 @prenotnull{event}
 241 @prenotnull{packet}
 242 @prehot{event}
 243 @pre The parent stream class of \p packet is the same as the parent
 244         stream class of \p event.
 245 @postsuccessrefcountretinc
 246
 247 @sa bt_event_get_packet(): Returns the associated packet of a
 248         given event object.
 249 */
 250 extern int bt_event_set_packet(struct bt_event *event,
 251                 struct bt_packet *packet);
 252
 253 extern struct bt_stream *bt_event_borrow_stream(struct bt_event *event);
 254
 255 /**
 256 @brief  Returns the parent CTF IR stream associated to the CTF IR event
 257         \p event.
 258
 259 @param[in] event        Event of which to get the parent stream.
 260 @returns                Parent stream of \p event, or \c NULL on error.
 261
 262 @prenotnull{event}
 263 @postrefcountsame{event}
 264 @postsuccessrefcountretinc
 265 */
 266 static inline
 267 struct bt_stream *bt_event_get_stream(struct bt_event *event)
 268 {
 269         return bt_get(bt_event_borrow_stream(event));
 270 }
 271
 272 /** @} */
 273
 274 /**
 275 @name Contained fields functions
 276 @{
 277 */
 278
 279 extern struct bt_field *bt_event_borrow_header(struct bt_event *event);
 280
 281 /**
 282 @brief  Returns the stream event header field of the CTF IR event
 283         \p event.
 284
 285 @param[in] event        Event of which to get the stream event header
 286                         field.
 287 @returns                Stream event header field of \p event,
 288                         or \c NULL if the stream event header
 289                         field is not set or on error.
 290
 291 @prenotnull{event}
 292 @postrefcountsame{event}
 293 @postsuccessrefcountretinc
 294
 295 @sa bt_event_get_header(): Sets the stream event header
 296         field of a given event.
 297 */
 298 static inline
 299 struct bt_field *bt_event_get_header(struct bt_event *event)
 300 {
 301         return bt_get(bt_event_borrow_header(event));
 302 }
 303
 304 /**
 305 @brief  Sets the stream event header field of the CTF IR event
 306         \p event to \p header, or unsets the current stream event header field
 307         from \p event.
 308
 309 If \p header is not \c NULL, the field type of \p header, as returned by
 310 bt_field_get_type(), \em must be equivalent to the field type returned by
 311 bt_stream_class_get_event_header_type() for the parent stream class
 312 of \p event.
 313
 314 @param[in] event        Event of which to set the stream event header
 315                         field.
 316 @param[in] header       Stream event header field.
 317 @returns                0 on success, or a negative value on error.
 318
 319 @prenotnull{event}
 320 @prehot{event}
 321 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
 322         the field type returned by bt_stream_class_get_event_header_type()
 323         for the parent stream class of \p event.
 324 @postrefcountsame{event}
 325 @post <strong>On success, if \p header is not \c NULL</strong>,
 326         the reference count of \p header is incremented.
 327
 328 @sa bt_event_get_header(): Returns the stream event header field
 329         of a given event.
 330 */
 331 extern int bt_event_set_header(struct bt_event *event,
 332                 struct bt_field *header);
 333
 334 extern struct bt_field *bt_event_borrow_stream_event_context(
 335                 struct bt_event *event);
 336
 337 /**
 338 @brief  Returns the stream event context field of the CTF IR event
 339         \p event.
 340
 341 @param[in] event        Event of which to get the stream event context
 342                         field.
 343 @returns                Stream event context field of \p event,
 344                         or \c NULL if the stream event context
 345                         field is not set or on error.
 346
 347 @prenotnull{event}
 348 @postrefcountsame{event}
 349 @postsuccessrefcountretinc
 350
 351 @sa bt_event_set_stream_event_context(): Sets the stream event context
 352         field of a given event.
 353 */
 354 static inline
 355 struct bt_field *bt_event_get_stream_event_context(struct bt_event *event)
 356 {
 357         return bt_get(bt_event_borrow_stream_event_context(event));
 358 }
 359
 360 /**
 361 @brief  Sets the stream event context field of the CTF IR event
 362         \p event to \p context, or unsets the current stream event context field
 363         from \p event.
 364
 365 If \p context is not \c NULL, the field type of \p context, as returned by
 366 bt_field_get_type(), \em must be equivalent to the field type returned by
 367 bt_stream_class_get_event_context_type() for the parent stream class
 368 of \p event.
 369
 370 @param[in] event        Event of which to set the stream event context field.
 371 @param[in] context      Stream event context field.
 372 @returns                0 on success, or a negative value on error.
 373
 374 @prenotnull{event}
 375 @prehot{event}
 376 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
 377         the field type returned by bt_stream_class_get_event_context_type()
 378         for the parent stream class of \p event.
 379 @postrefcountsame{event}
 380 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
 381         count of \p context is incremented.
 382
 383 @sa bt_event_get_stream_event_context(): Returns the stream event context
 384         field of a given event.
 385 */
 386 extern int bt_event_set_stream_event_context(struct bt_event *event,
 387                 struct bt_field *context);
 388
 389 extern struct bt_field *bt_event_borrow_context(struct bt_event *event);
 390
 391 /**
 392 @brief  Returns the event context field of the CTF IR event \p event.
 393
 394 @param[in] event        Event of which to get the context field.
 395 @returns                Event context field of \p event, or \c NULL if the
 396                         event context field is not set or on error.
 397
 398 @prenotnull{event}
 399 @postrefcountsame{event}
 400 @postsuccessrefcountretinc
 401
 402 @sa bt_event_set_context(): Sets the event context field of a given
 403         event.
 404 */
 405 static inline
 406 struct bt_field *bt_event_get_context(struct bt_event *event)
 407 {
 408         return bt_get(bt_event_borrow_context(event));
 409 }
 410
 411 /**
 412 @brief  Sets the event context field of the CTF IR event \p event to \p context,
 413         or unsets the current event context field from \p event.
 414
 415 If \p context is not \c NULL, the field type of \p context, as returned by
 416 bt_field_get_type(), \em must be equivalent to the field type returned by
 417 bt_event_class_get_context_type() for the parent class of \p event.
 418
 419 @param[in] event        Event of which to set the context field.
 420 @param[in] context      Event context field.
 421 @returns                0 on success, or a negative value on error.
 422
 423 @prenotnull{event}
 424 @prehot{event}
 425 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
 426         the field type returned by bt_event_class_get_context_type() for the
 427         parent class of \p event.
 428 @postrefcountsame{event}
 429 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
 430         count of \p context is incremented.
 431
 432 @sa bt_event_get_context(): Returns the context field of a given event.
 433 */
 434 extern int bt_event_set_context(struct bt_event *event,
 435                 struct bt_field *context);
 436
 437 extern struct bt_field *bt_event_borrow_payload(struct bt_event *event);
 438
 439 /**
 440 @brief  Returns the payload field of the CTF IR event \p event.
 441
 442 @param[in] event        Event of which to get the payload field.
 443 @returns                Payload field of \p event, or \c NULL if the payload
 444                         field is not set or on error.
 445
 446 @prenotnull{event}
 447 @postrefcountsame{event}
 448 @postsuccessrefcountretinc
 449
 450 @sa bt_event_set_payload(): Sets the payload field of a given
 451         event.
 452 */
 453 static inline
 454 struct bt_field *bt_event_get_payload(struct bt_event *event)
 455 {
 456         return bt_get(bt_event_borrow_payload(event));
 457 }
 458
 459 /**
 460 @brief  Sets the payload field of the CTF IR event \p event to \p payload,
 461         or unsets the current event payload field from \p event.
 462
 463 If \p payload is not \c NULL, the field type of \p payload, as returned by
 464 bt_field_get_type(), \em must be equivalent to the field type returned by
 465 bt_event_class_get_payload_type() for the parent class of \p event.
 466
 467 @param[in] event        Event of which to set the payload field.
 468 @param[in] payload      Event payload field.
 469 @returns                0 on success, or a negative value on error.
 470
 471 @prenotnull{event}
 472 @prehot{event}
 473 @pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
 474         the field typereturned by bt_event_class_get_payload_type() for the
 475         parent class of \p event.
 476 @postrefcountsame{event}
 477 @post <strong>On success, if \p payload is not \c NULL</strong>, the reference
 478         count of \p payload is incremented.
 479
 480 @sa bt_event_get_payload(): Returns the payload field of a given event.
 481 */
 482 extern int bt_event_set_payload(struct bt_event *event,
 483                 struct bt_field *payload);
 484
 485 /** @} */
 486
 487 /**
 488 @name Clock value functions
 489 @{
 490 */
 491
 492 extern struct bt_clock_value *bt_event_borrow_clock_value(
 493                 struct bt_event *event,
 494                 struct bt_clock_class *clock_class);
 495
 496 /**
 497 @brief  Returns the value, as of the CTF IR event \p event, of the
 498         clock described by the
 499         \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
 500
 501 @param[in] event        Event of which to get the value of the clock
 502                         described by \p clock_class.
 503 @param[in] clock_class  Class of the clock of which to get the value.
 504 @returns                Value of the clock described by \p clock_class
 505                         as of \p event.
 506
 507 @prenotnull{event}
 508 @prenotnull{clock_class}
 509 @postrefcountsame{event}
 510 @postrefcountsame{clock_class}
 511 @postsuccessrefcountretinc
 512
 513 @sa bt_event_set_clock_value(): Sets the clock value of a given event.
 514 */
 515 static inline
 516 struct bt_clock_value *bt_event_get_clock_value(
 517                 struct bt_event *event,
 518                 struct bt_clock_class *clock_class)
 519 {
 520         return bt_get(bt_event_borrow_clock_value(event, clock_class));
 521 }
 522
 523 /**
 524 @brief  Sets the value, as of the CTF IR event \p event, of the
 525         clock described by its \link ctfirclockclass CTF IR
 526         clock class\endlink.
 527
 528 @param[in] event        Event of which to set the value of the clock
 529                         described by the clock class of \p clock_value.
 530 @param[in] clock_value  Value of the clock described by its clock class
 531                         as of \p event.
 532 @returns                0 on success, or a negative value on error.
 533
 534 @prenotnull{event}
 535 @prenotnull{clock_value}
 536 @prehot{event}
 537 @postrefcountsame{event}
 538
 539 @sa bt_event_get_clock_value(): Returns the clock value of
 540         a given event.
 541 */
 542 extern int bt_event_set_clock_value(
 543                 struct bt_event *event,
 544                 struct bt_clock_value *clock_value);
 545
 546 /** @} */
 547
 548 /** @} */
 549
 550 #ifdef __cplusplus
 551 }
 552 #endif
 553
 554 #endif /* BABELTRACE_CTF_IR_EVENT_H */