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