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