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