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 #include <stdint.h>
  34 #include <stddef.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_value;
  41 struct bt_clock_class;
  42
  43 /**
  44 @defgroup ctfirevent CTF IR event
  45 @ingroup ctfir
  46 @brief CTF IR event.
  47
  48 @code
  49 #include <babeltrace/ctf-ir/event.h>
  50 @endcode
  51
  52 A CTF IR <strong><em>event</em></strong> is a container of event
  53 fields:
  54
  55 - <strong>Stream event header</strong> field, described by the
  56   <em>stream event header field type</em> of a
  57   \link ctfirstreamclass CTF IR stream class\endlink.
  58 - <strong>Stream event context</strong> field, described by the
  59   <em>stream event context field type</em> of a stream class.
  60 - <strong>Event context</strong> field, described by the
  61   <em>event context field type</em> of a
  62   \link ctfireventclass CTF IR event class\endlink.
  63 - <strong>Event payload</strong>, described by the
  64   <em>event payload field type</em> of an event class.
  65
  66 As a reminder, here's the structure of a CTF packet:
  67
  68 @imgpacketstructure
  69
  70 You can create a CTF IR event \em from a
  71 \link ctfireventclass CTF IR event class\endlink with
  72 bt_event_create(). The event class you use to create an event
  73 object becomes its parent.
  74
  75 If the \link ctfirtraceclass CTF IR trace class\endlink of an event
  76 object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
  77 which is the parent of its event class) was created by a
  78 \link ctfwriter CTF writer\endlink object, then the only possible
  79 action you can do with this event object is to append it to a
  80 \link ctfirstream CTF IR stream\endlink with
  81 bt_stream_append_event(). Otherwise, you can create an event
  82 notification with bt_notification_event_create(). The event you pass
  83 to this function \em must have an attached packet object first.
  84
  85 You can attach a \link ctfirpacket CTF IR packet object\endlink to an
  86 event object with bt_event_set_packet().
  87
  88 A CTF IR event has a mapping of
  89 \link ctfirclockvalue CTF IR clock values\endlink. A clock value is
  90 an instance of a specific
  91 \link ctfirclockclass CTF IR clock class\endlink when the event is
  92 emitted. You can set an event object's clock value with
  93 bt_event_set_clock_value().
  94
  95 As with any Babeltrace object, CTF IR event objects have
  96 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  97 counts</a>. See \ref refs to learn more about the reference counting
  98 management of Babeltrace objects.
  99
 100 bt_notification_event_create() \em freezes its event parameter on
 101 success. You cannot modify a frozen event object: it is considered
 102 immutable, except for \link refs reference counting\endlink.
 103
 104 @sa ctfireventclass
 105 @sa ctfirpacket
 106
 107 @file
 108 @brief CTF IR event type and functions.
 109 @sa ctfirevent
 110
 111 @addtogroup ctfirevent
 112 @{
 113 */
 114
 115 /**
 116 @struct bt_event
 117 @brief A CTF IR event.
 118 @sa ctfirevent
 119 */
 120 struct bt_event;
 121 struct bt_clock;
 122 struct bt_clock_value;
 123 struct bt_event_class;
 124 struct bt_field;
 125 struct bt_field_type;
 126 struct bt_stream_class;
 127 struct bt_packet;
 128
 129 /**
 130 @name Creation and parent access functions
 131 @{
 132 */
 133
 134 /**
 135 @brief  Creates a default CTF IR event from the CTF IR event class
 136         \p event_class.
 137
 138 \p event_class \em must have a parent
 139 \link ctfirstreamclass CTF IR stream class\endlink.
 140
 141 On success, the four fields of the created event object are not set. You
 142 can set them with bt_event_set_header(),
 143 bt_event_set_stream_event_context(),
 144 bt_event_set_event_context(), and bt_event_set_event_payload().
 145
 146 This function tries to resolve the needed
 147 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 148 types that are found anywhere in the context or payload field
 149 types of \p event_class and in the root field types of the
 150 parent stream class of \p event_class. If any automatic resolving fails,
 151 this function fails. This means that, if any dynamic field type need
 152 a field type which should be found in the trace packet header root
 153 field type, and if the parent stream class of \p event_class was not
 154 added to a \link ctfirtraceclass CTF IR trace class\endlink yet
 155 with bt_trace_add_stream_class(), then this function fails.
 156
 157 @param[in] event_class  CTF IR event class to use to create the
 158                         CTF IR event.
 159 @returns                Created event object, or \c NULL on error.
 160
 161 @prenotnull{event_class}
 162 @pre \p event_class has a parent stream class.
 163 @postsuccessrefcountret1
 164 */
 165 extern struct bt_event *bt_event_create(
 166                 struct bt_event_class *event_class);
 167
 168 /**
 169 @brief  Returns the parent CTF IR event class of the CTF IR event
 170         \p event.
 171
 172 This function returns a reference to the event class which was used to
 173 create the event object in the first place with bt_event_create().
 174
 175 @param[in] event        Event of which to get the parent event class.
 176 @returns                Parent event class of \p event,
 177                         or \c NULL on error.
 178
 179 @prenotnull{event}
 180 @postrefcountsame{event}
 181 @postsuccessrefcountretinc
 182 */
 183 extern struct bt_event_class *bt_event_get_class(
 184                 struct bt_event *event);
 185
 186 /**
 187 @brief  Returns the CTF IR packet associated to the CTF IR event
 188         \p event.
 189
 190 This function returns a reference to the event class which was set to
 191 \p event in the first place with bt_event_set_packet().
 192
 193 @param[in] event        Event of which to get the associated packet.
 194 @returns                Packet associated to \p event,
 195                         or \c NULL if no packet is associated to
 196                         \p event or on error.
 197
 198 @prenotnull{event}
 199 @postrefcountsame{event}
 200 @postsuccessrefcountretinc
 201
 202 @sa bt_event_set_packet(): Associates a given event to a given
 203         packet.
 204 */
 205 extern struct bt_packet *bt_event_get_packet(
 206                 struct bt_event *event);
 207
 208 /**
 209 @brief  Associates the CTF IR event \p event to the CTF IR packet
 210         \p packet.
 211
 212 The \link ctfirstreamclass CTF IR stream class\endlink of the
 213 parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
 214 be the same as the parent stream class of the
 215 \link ctfireventclass CTF IR event class\endlink returned
 216 by bt_event_get_class() for \p event.
 217
 218 You \em must call this function to create an event-packet association
 219 before you call bt_notification_event_create() with \p event.
 220
 221 On success, this function also sets the parent stream object of
 222 \p event to the parent stream of \p packet.
 223
 224 @param[in] event        Event to which to associate \p packet.
 225 @param[in] packet       Packet to associate to \p event.
 226 @returns                0 on success, or a negative value on error.
 227
 228 @prenotnull{event}
 229 @prenotnull{packet}
 230 @prehot{event}
 231 @pre The parent stream class of \p packet is the same as the parent
 232         stream class of \p event.
 233 @postsuccessrefcountretinc
 234
 235 @sa bt_event_get_packet(): Returns the associated packet of a
 236         given event object.
 237 */
 238 extern int bt_event_set_packet(struct bt_event *event,
 239                 struct bt_packet *packet);
 240
 241 /**
 242 @brief  Returns the parent CTF IR stream associated to the CTF IR event
 243         \p event.
 244
 245 @param[in] event        Event of which to get the parent stream.
 246 @returns                Parent stream of \p event, or \c NULL on error.
 247
 248 @prenotnull{event}
 249 @postrefcountsame{event}
 250 @postsuccessrefcountretinc
 251 */
 252 extern struct bt_stream *bt_event_get_stream(
 253                 struct bt_event *event);
 254
 255 /** @} */
 256
 257 /**
 258 @name Contained fields functions
 259 @{
 260 */
 261
 262 /**
 263 @brief  Returns the stream event header field of the CTF IR event
 264         \p event.
 265
 266 @param[in] event        Event of which to get the stream event header
 267                         field.
 268 @returns                Stream event header field of \p event,
 269                         or \c NULL if the stream event header
 270                         field is not set or on error.
 271
 272 @prenotnull{event}
 273 @postrefcountsame{event}
 274 @postsuccessrefcountretinc
 275
 276 @sa bt_event_get_header(): Sets the stream event header
 277         field of a given event.
 278 */
 279 extern struct bt_field *bt_event_get_header(
 280                 struct bt_event *event);
 281
 282 /**
 283 @brief  Sets the stream event header field of the CTF IR event
 284         \p event to \p header, or unsets the current stream event header field
 285         from \p event.
 286
 287 If \p header is not \c NULL, the field type of \p header, as returned by
 288 bt_field_get_type(), \em must be equivalent to the field type returned by
 289 bt_stream_class_get_event_header_type() for the parent stream class
 290 of \p event.
 291
 292 @param[in] event        Event of which to set the stream event header
 293                         field.
 294 @param[in] header       Stream event header field.
 295 @returns                0 on success, or a negative value on error.
 296
 297 @prenotnull{event}
 298 @prehot{event}
 299 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
 300         the field type returned by bt_stream_class_get_event_header_type()
 301         for the parent stream class of \p event.
 302 @postrefcountsame{event}
 303 @post <strong>On success, if \p header is not \c NULL</strong>,
 304         the reference count of \p header is incremented.
 305
 306 @sa bt_event_get_header(): Returns the stream event header field
 307         of a given event.
 308 */
 309 extern int bt_event_set_header(struct bt_event *event,
 310                 struct bt_field *header);
 311
 312 /**
 313 @brief  Returns the stream event context field of the CTF IR event
 314         \p event.
 315
 316 @param[in] event        Event of which to get the stream event context
 317                         field.
 318 @returns                Stream event context field of \p event,
 319                         or \c NULL if the stream event context
 320                         field is not set or on error.
 321
 322 @prenotnull{event}
 323 @postrefcountsame{event}
 324 @postsuccessrefcountretinc
 325
 326 @sa bt_event_set_stream_event_context(): Sets the stream event context
 327         field of a given event.
 328 */
 329 extern struct bt_field *bt_event_get_stream_event_context(
 330                 struct bt_event *event);
 331
 332 /**
 333 @brief  Sets the stream event context field of the CTF IR event
 334         \p event to \p context, or unsets the current stream event context field
 335         from \p event.
 336
 337 If \p context is not \c NULL, the field type of \p context, as returned by
 338 bt_field_get_type(), \em must be equivalent to the field type returned by
 339 bt_stream_class_get_event_context_type() for the parent stream class
 340 of \p event.
 341
 342 @param[in] event        Event of which to set the stream event context field.
 343 @param[in] context      Stream event context field.
 344 @returns                0 on success, or a negative value on error.
 345
 346 @prenotnull{event}
 347 @prehot{event}
 348 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
 349         the field type returned by bt_stream_class_get_event_context_type()
 350         for the parent stream class of \p event.
 351 @postrefcountsame{event}
 352 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
 353         count of \p context is incremented.
 354
 355 @sa bt_event_get_stream_event_context(): Returns the stream event context
 356         field of a given event.
 357 */
 358 extern int bt_event_set_stream_event_context(struct bt_event *event,
 359                 struct bt_field *context);
 360
 361 /**
 362 @brief  Returns the event context field of the CTF IR event \p event.
 363
 364 @param[in] event        Event of which to get the context field.
 365 @returns                Event context field of \p event, or \c NULL if the
 366                         event context field is not set or on error.
 367
 368 @prenotnull{event}
 369 @postrefcountsame{event}
 370 @postsuccessrefcountretinc
 371
 372 @sa bt_event_set_event_context(): Sets the event context field of a given
 373         event.
 374 */
 375 extern struct bt_field *bt_event_get_event_context(
 376                 struct bt_event *event);
 377
 378 /**
 379 @brief  Sets the event context field of the CTF IR event \p event to \p context,
 380         or unsets the current event context field from \p event.
 381
 382 If \p context is not \c NULL, the field type of \p context, as returned by
 383 bt_field_get_type(), \em must be equivalent to the field type returned by
 384 bt_event_class_get_context_type() for the parent class of \p event.
 385
 386 @param[in] event        Event of which to set the context field.
 387 @param[in] context      Event context field.
 388 @returns                0 on success, or a negative value on error.
 389
 390 @prenotnull{event}
 391 @prehot{event}
 392 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
 393         the field type returned by bt_event_class_get_context_type() for the
 394         parent class of \p event.
 395 @postrefcountsame{event}
 396 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
 397         count of \p context is incremented.
 398
 399 @sa bt_event_get_context(): Returns the context field of a given event.
 400 */
 401 extern int bt_event_set_event_context(struct bt_event *event,
 402                 struct bt_field *context);
 403
 404 /**
 405 @brief  Returns the payload field of the CTF IR event \p event.
 406
 407 @param[in] event        Event of which to get the payload field.
 408 @returns                Payload field of \p event, or \c NULL if the payload
 409                         field is not set or on error.
 410
 411 @prenotnull{event}
 412 @postrefcountsame{event}
 413 @postsuccessrefcountretinc
 414
 415 @sa bt_event_set_event_payload(): Sets the payload field of a given
 416         event.
 417 */
 418 extern struct bt_field *bt_event_get_event_payload(
 419                 struct bt_event *event);
 420
 421 /**
 422 @brief  Sets the payload field of the CTF IR event \p event to \p payload,
 423         or unsets the current event payload field from \p event.
 424
 425 If \p payload is not \c NULL, the field type of \p payload, as returned by
 426 bt_field_get_type(), \em must be equivalent to the field type returned by
 427 bt_event_class_get_payload_type() for the parent class of \p event.
 428
 429 @param[in] event        Event of which to set the payload field.
 430 @param[in] payload      Event payload field.
 431 @returns                0 on success, or a negative value on error.
 432
 433 @prenotnull{event}
 434 @prehot{event}
 435 @pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
 436         the field typereturned by bt_event_class_get_payload_type() for the
 437         parent class of \p event.
 438 @postrefcountsame{event}
 439 @post <strong>On success, if \p payload is not \c NULL</strong>, the reference
 440         count of \p payload is incremented.
 441
 442 @sa bt_event_get_payload(): Returns the payload field of a given event.
 443 */
 444 extern int bt_event_set_event_payload(struct bt_event *event,
 445                 struct bt_field *payload);
 446
 447 /** @cond DOCUMENT */
 448
 449 /*
 450  * TODO: Doxygenize.
 451  *
 452  * bt_event_get_payload: get an event's field.
 453  *
 454  * Returns the field matching "name". bt_put() must be called on the
 455  * returned value.
 456  *
 457  * @param event Event instance.
 458  * @param name Event field name, see notes.
 459  *
 460  * Returns a field instance on success, NULL on error.
 461  *
 462  * Note: Passing a name will cause the function to perform a look-up by
 463  *      name assuming the event's payload is a structure. This will return
 464  *      the raw payload instance if name is NULL.
 465  */
 466 extern struct bt_field *bt_event_get_payload(struct bt_event *event,
 467                 const char *name);
 468
 469 /*
 470  * TODO: Doxygenize.
 471  *
 472  * bt_event_get_payload_by_index: Get event's field by index.
 473  *
 474  * Returns the field associated with the provided index. bt_put()
 475  * must be called on the returned value. The indexes to be provided are
 476  * the same as can be retrieved from the event class.
 477  *
 478  * @param event Event.
 479  * @param index Index of field.
 480  *
 481  * Returns the event's field, NULL on error.
 482  *
 483  * Note: Will return an error if the payload's type is not a structure.
 484  */
 485 extern struct bt_field *bt_event_get_payload_by_index(
 486                 struct bt_event *event, uint64_t index);
 487
 488 /*
 489  * TODO: Doxygenize.
 490  *
 491  * bt_event_set_payload: set an event's field.
 492  *
 493  * Set a manually allocated field as an event's payload. The event will share
 494  * the field's ownership by using its reference count.
 495  * bt_put() must be called on the returned value.
 496  *
 497  * @param event Event instance.
 498  * @param name Event field name, see notes.
 499  * @param value Instance of a field whose type corresponds to the event's field.
 500  *
 501  * Returns 0 on success, a negative value on error.
 502  *
 503  * Note: The function will return an error if a name is provided and the payload
 504  *      type is not a structure. If name is NULL, the payload field will be set
 505  *      directly and must match the event class' payload's type.
 506  */
 507 extern int bt_event_set_payload(struct bt_event *event,
 508                 const char *name,
 509                 struct bt_field *value);
 510
 511 /** @endcond */
 512
 513 /** @} */
 514
 515 /**
 516 @name Clock value functions
 517 @{
 518 */
 519
 520 /**
 521 @brief  Returns the value, as of the CTF IR event \p event, of the
 522         clock described by the
 523         \link ctfirclockclass CTF IR clock class\endlink \p clock_class.
 524
 525 @param[in] event        Event of which to get the value of the clock
 526                         described by \p clock_class.
 527 @param[in] clock_class  Class of the clock of which to get the value.
 528 @returns                Value of the clock described by \p clock_class
 529                         as of \p event.
 530
 531 @prenotnull{event}
 532 @prenotnull{clock_class}
 533 @postrefcountsame{event}
 534 @postrefcountsame{clock_class}
 535 @postsuccessrefcountretinc
 536
 537 @sa bt_event_set_clock_value(): Sets the clock value of a given event.
 538 */
 539 extern struct bt_clock_value *bt_event_get_clock_value(
 540                 struct bt_event *event,
 541                 struct bt_clock_class *clock_class);
 542
 543 /**
 544 @brief  Sets the value, as of the CTF IR event \p event, of the
 545         clock described by its \link ctfirclockclass CTF IR
 546         clock class\endlink.
 547
 548 @param[in] event        Event of which to set the value of the clock
 549                         described by the clock class of \p clock_value.
 550 @param[in] clock_value  Value of the clock described by its clock class
 551                         as of \p event.
 552 @returns                0 on success, or a negative value on error.
 553
 554 @prenotnull{event}
 555 @prenotnull{clock_value}
 556 @prehot{event}
 557 @postrefcountsame{event}
 558
 559 @sa bt_event_get_clock_value(): Returns the clock value of
 560         a given event.
 561 */
 562 extern int bt_event_set_clock_value(
 563                 struct bt_event *event,
 564                 struct bt_clock_value *clock_value);
 565
 566 /** @} */
 567
 568 /** @} */
 569
 570 /* Pre-2.0 CTF writer compatibility */
 571 #define bt_ctf_event bt_event
 572 #define bt_ctf_event_create bt_event_create
 573 #define bt_ctf_event_get_payload bt_event_get_payload
 574 #define bt_ctf_event_set_payload bt_event_set_payload
 575
 576 #ifdef __cplusplus
 577 }
 578 #endif
 579
 580 #endif /* BABELTRACE_CTF_IR_EVENT_H */