include/babeltrace/ctf-ir/stream-class.h

   1 #ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
   2 #define BABELTRACE_CTF_IR_STREAM_CLASS_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream Class
   6  *
   7  * Copyright 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
  35 /* For bt_get() */
  36 #include <babeltrace/ref.h>
  37
  38 /* For bt_visitor */
  39 #include <babeltrace/ctf-ir/visitor.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /**
  46 @defgroup ctfirstreamclass CTF IR stream class
  47 @ingroup ctfir
  48 @brief CTF IR stream class.
  49
  50 @code
  51 #include <babeltrace/ctf-ir/stream-class.h>
  52 @endcode
  53
  54 @note
  55 See \ref ctfwriterstreamclass which documents additional CTF IR stream
  56 class functions exclusive to the CTF writer mode.
  57
  58 A CTF IR <strong><em>stream class</em></strong> is a template that you
  59 can use to create concrete \link ctfirstream CTF IR streams\endlink.
  60
  61 A stream class has the following properties, both of which \em must
  62 be unique amongst all the stream classes contained in the same
  63 \link ctfirtraceclass CTF IR trace class\endlink:
  64
  65 - A \b name.
  66 - A numeric \b ID.
  67
  68 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
  69 contains zero or more stream classes,
  70 and a stream class contains zero or more
  71 \link ctfireventclass event classes\endlink.
  72 You can add an event class
  73 to a stream class with bt_stream_class_add_event_class().
  74 You can add a stream class to a trace class with
  75 bt_trace_add_stream_class().
  76
  77 A stream class owns three \link ctfirfieldtypes field types\endlink:
  78
  79 - An optional <strong>stream packet context</strong> field type, which
  80   represents the \c stream.packet.context CTF scope.
  81 - An optional <strong>stream event header</strong> field type, which
  82   represents the \c stream.event.header CTF scope.
  83 - An optional <strong>stream event context</strong> field type, which
  84   represents the \c stream.event.context CTF scope.
  85
  86 Those three field types \em must be structure field types as of
  87 Babeltrace \btversion.
  88
  89 As per the CTF specification, the event header field type \em must
  90 contain a field named \c id if the stream class contains more than one
  91 event class.
  92
  93 As a reminder, here's the structure of a CTF packet:
  94
  95 @imgpacketstructure
  96
  97 Before you can create a stream from a stream class with
  98 bt_stream_create(), you \em must add the prepared stream class to a
  99 trace class by calling bt_trace_add_stream_class().
 100
 101 As with any Babeltrace object, CTF IR stream class objects have
 102 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 103 counts</a>. See \ref refs to learn more about the reference counting
 104 management of Babeltrace objects.
 105
 106 The following functions \em freeze their stream class parameter on
 107 success:
 108
 109 - bt_trace_add_stream_class()
 110 - bt_event_create()
 111 - bt_writer_create_stream()
 112   (\link ctfwriter CTF writer\endlink mode only)
 113
 114 You cannot modify a frozen stream class: it is considered immutable,
 115 except for:
 116
 117 - Adding an event class to it with
 118   bt_stream_class_add_event_class(). If the stream class's parent
 119   \link ctfirtraceclass trace class\endlink is static, however,
 120   you cannot call bt_stream_class_add_event_class()
 121   (see bt_trace_is_static() and bt_trace_set_is_static()).
 122 - \link refs Reference counting\endlink.
 123
 124 @sa ctfirstream
 125 @sa ctfireventclass
 126 @sa ctfirtraceclass
 127 @sa ctfwriterstreamclass
 128
 129 @file
 130 @brief CTF IR stream class type and functions.
 131 @sa ctfirstreamclass
 132
 133 @addtogroup ctfirstreamclass
 134 @{
 135 */
 136
 137 /**
 138 @struct bt_stream_class
 139 @brief A CTF IR stream class.
 140 @sa ctfirstreamclass
 141 */
 142 struct bt_stream_class;
 143 struct bt_event_class;
 144 struct bt_clock;
 145
 146 /**
 147 @name Creation and parent access functions
 148 @{
 149 */
 150
 151 /**
 152 @brief  Creates a default CTF IR stream class named \p name, or a
 153         default unnamed stream class if \p name is \c NULL.
 154
 155 On success, the packet context field type of the created stream class
 156 has the following fields:
 157
 158 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
 159 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
 160 - <code>content_size</code>: a 64-bit unsigned integer field type.
 161 - <code>packet_size</code>: a 64-bit unsigned integer field type.
 162 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
 163
 164 On success, the event header field type of the created stream class
 165 has the following fields:
 166
 167 - <code>code</code>: a 32-bit unsigned integer field type.
 168 - <code>timestamp</code>: a 64-bit unsigned integer field type.
 169
 170 You can modify those default field types after the stream class is
 171 created with bt_stream_class_set_packet_context_field_type() and
 172 bt_stream_class_set_event_header_field_type().
 173
 174 @param[in] name Name of the stream class to create (copied on success),
 175                 or \c NULL to create an unnamed stream class.
 176 @returns        Created default stream class, or \c NULL on error.
 177
 178 @postsuccessrefcountret1
 179
 180 @sa bt_stream_class_create_empty(): Creates an empty stream class.
 181 */
 182 extern struct bt_stream_class *bt_stream_class_create(const char *name);
 183
 184 extern struct bt_trace *bt_stream_class_borrow_trace(
 185                 struct bt_stream_class *stream_class);
 186
 187 /**
 188 @brief  Returns the parent CTF IR trace class of the CTF IR stream
 189         class \p stream_class.
 190
 191 It is possible that the stream class was not added to a trace class
 192 yet, in which case this function returns \c NULL. You can add a
 193 stream class to a trace class with
 194 bt_trace_add_stream_class().
 195
 196 @param[in] stream_class Stream class of which to get the parent
 197                         trace class.
 198 @returns                Parent trace class of \p stream_class,
 199                         or \c NULL if \p stream_class was not
 200                         added to a trace class yet or on error.
 201
 202 @prenotnull{stream_class}
 203 @postrefcountsame{stream_class}
 204 @postsuccessrefcountretinc
 205
 206 @sa bt_trace_add_stream_class(): Add a stream class to
 207         a trace class.
 208 */
 209 static inline
 210 struct bt_trace *bt_stream_class_get_trace(
 211                 struct bt_stream_class *stream_class)
 212 {
 213         return bt_get(bt_stream_class_borrow_trace(stream_class));
 214 }
 215
 216 /** @} */
 217
 218 /**
 219 @name Properties functions
 220 @{
 221 */
 222
 223 /**
 224 @brief  Returns the name of the CTF IR stream class \p stream_class.
 225
 226 On success, \p stream_class remains the sole owner of the returned
 227 string.
 228
 229 @param[in] stream_class Stream class of which to get the name.
 230 @returns                Name of stream class \p stream_class, or
 231                         \c NULL if \p stream_class is unnamed or
 232                         on error.
 233
 234 @prenotnull{stream_class}
 235 @postrefcountsame{stream_class}
 236
 237 @sa bt_stream_class_set_name(): Sets the name of a given
 238         stream class.
 239 */
 240 extern const char *bt_stream_class_get_name(
 241                 struct bt_stream_class *stream_class);
 242
 243 /**
 244 @brief  Sets the name of the CTF IR stream class
 245         \p stream_class to \p name, or resets the name of
 246         \p stream_class.
 247
 248 If \p name is not \c NULL, it must be unique amongst the names of all
 249 the stream classes of the trace class to which you eventually add
 250 \p stream_class.
 251
 252 @param[in] stream_class Stream class of which to set the name.
 253 @param[in] name         Name of the stream class (copied on success), or
 254                         \c NULL to reset the name of \p stream_class
 255                         (make it unnamed).
 256 @returns                0 on success, or a negative value on error.
 257
 258 @prenotnull{stream_class}
 259 @prehot{stream_class}
 260 @postrefcountsame{stream_class}
 261
 262 @sa bt_stream_class_get_name(): Returns the name of a given
 263         stream class.
 264 */
 265 extern int bt_stream_class_set_name(
 266                 struct bt_stream_class *stream_class, const char *name);
 267
 268 /**
 269 @brief  Returns the numeric ID of the CTF IR stream class \p stream_class.
 270
 271 @param[in] stream_class Stream class of which to get the numeric ID.
 272 @returns                ID of stream class \p stream_class, or a
 273                         negative value on error.
 274
 275 @prenotnull{stream_class}
 276 @postrefcountsame{stream_class}
 277
 278 @sa bt_stream_class_set_id(): Sets the numeric ID of a given
 279         stream class.
 280 */
 281 extern int64_t bt_stream_class_get_id(
 282                 struct bt_stream_class *stream_class);
 283
 284 /**
 285 @brief  Sets the numeric ID of the CTF IR stream class
 286         \p stream_class to \p id.
 287
 288 \p id must be unique amongst the IDs of all the stream classes
 289 of the trace class to which you eventually add \p stream_class.
 290
 291 @param[in] stream_class Stream class of which to set the numeric ID.
 292 @param[in] id           ID of the stream class.
 293 @returns                0 on success, or a negative value on error.
 294
 295 @prenotnull{stream_class}
 296 @prehot{stream_class}
 297 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 298 @postrefcountsame{stream_class}
 299
 300 @sa bt_stream_class_get_id(): Returns the numeric ID of a given
 301         stream class.
 302 */
 303 extern int bt_stream_class_set_id(
 304                 struct bt_stream_class *stream_class, uint64_t id);
 305
 306 /** @} */
 307
 308 /**
 309 @name Contained field types functions
 310 @{
 311 */
 312
 313 extern struct bt_field_type *bt_stream_class_borrow_packet_context_field_type(
 314                 struct bt_stream_class *stream_class);
 315
 316 /**
 317 @brief  Returns the packet context field type of the CTF IR stream class
 318         \p stream_class.
 319
 320 @param[in] stream_class Stream class of which to get the packet
 321                         context field type.
 322 @returns                Packet context field type of \p stream_class,
 323                         or \c NULL if \p stream_class has no packet context
 324                         field type or on error.
 325
 326 @prenotnull{stream_class}
 327 @postrefcountsame{stream_class}
 328 @post <strong>On success, if the return value is a field type</strong>, its
 329         reference count is incremented.
 330
 331 @sa bt_stream_class_set_packet_context_field_type(): Sets the packet
 332         context field type of a given stream class.
 333 */
 334 static inline
 335 struct bt_field_type *bt_stream_class_get_packet_context_field_type(
 336                 struct bt_stream_class *stream_class)
 337 {
 338         return bt_get(bt_stream_class_borrow_packet_context_field_type(
 339                 stream_class));
 340 }
 341
 342 /**
 343 @brief  Sets the packet context field type of the CTF IR stream class
 344         \p stream_class to \p packet_context_type, or unsets the current packet
 345         context field type from \p stream_class.
 346
 347 If \p packet_context_type is \c NULL, then this function unsets the current
 348 packet context field type from \p stream_class, effectively making
 349 \p stream_class a stream class without a packet context field type.
 350
 351 As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
 352 \p packet_context_type \em must be a CTF IR structure field type object.
 353
 354 @param[in] stream_class         Stream class of which to set the packet
 355                                 context field type.
 356 @param[in] packet_context_type  Packet context field type, or \c NULL to unset
 357                                 the current packet context field type.
 358 @returns                        0 on success, or a negative value on error.
 359
 360 @prenotnull{stream_class}
 361 @prehot{stream_class}
 362 @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
 363         structure field type.
 364 @postrefcountsame{stream_class}
 365 @post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
 366         the reference count of \p packet_context_type is incremented.
 367
 368 @sa bt_stream_class_get_packet_context_field_type(): Returns the packet
 369         context field type of a given stream class.
 370 */
 371 extern int bt_stream_class_set_packet_context_field_type(
 372                 struct bt_stream_class *stream_class,
 373                 struct bt_field_type *packet_context_type);
 374
 375 extern struct bt_field_type *
 376 bt_stream_class_borrow_event_header_field_type(
 377                 struct bt_stream_class *stream_class);
 378
 379 /**
 380 @brief  Returns the event header field type of the CTF IR stream class
 381         \p stream_class.
 382
 383 @param[in] stream_class Stream class of which to get the event header
 384                         field type.
 385 @returns                Event header field type of \p stream_class,
 386                         or \c NULL if \p stream_class has no event header field
 387                         type or on error.
 388
 389 @prenotnull{stream_class}
 390 @postrefcountsame{stream_class}
 391 @post <strong>On success, if the return value is a field type</strong>, its
 392         reference count is incremented.
 393
 394 @sa bt_stream_class_set_event_header_field_type(): Sets the event
 395         header field type of a given stream class.
 396 */
 397 static inline
 398 struct bt_field_type *bt_stream_class_get_event_header_field_type(
 399                 struct bt_stream_class *stream_class)
 400 {
 401         return bt_get(bt_stream_class_borrow_event_header_field_type(
 402                 stream_class));
 403 }
 404
 405 /**
 406 @brief  Sets the event header field type of the CTF IR stream class
 407         \p stream_class to \p event_header_type, or unsets the current event
 408         header field type from \p stream_class.
 409
 410 If \p event_header_type is \c NULL, then this function unsets the current
 411 event header field type from \p stream_class, effectively making \p stream_class
 412 a stream class without a event header field type.
 413
 414 As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
 415 \p event_header_type \em must be a CTF IR structure field type object.
 416
 417 @param[in] stream_class         Stream class of which to set the event
 418                                 header field type.
 419 @param[in] event_header_type    Event header field type, or \c NULL to unset
 420                                 the current event header field type.
 421 @returns                        0 on success, or a negative value on error.
 422
 423 @prenotnull{stream_class}
 424 @prehot{stream_class}
 425 @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
 426         structure field type.
 427 @postrefcountsame{stream_class}
 428 @post <strong>On success, if \p event_header_type is not \c NULL</strong>,
 429         the reference count of \p event_header_type is incremented.
 430
 431 @sa bt_stream_class_get_event_header_field_type(): Returns the event
 432         header field type of a given stream class.
 433 */
 434 extern int bt_stream_class_set_event_header_field_type(
 435                 struct bt_stream_class *stream_class,
 436                 struct bt_field_type *event_header_type);
 437
 438 extern struct bt_field_type *
 439 bt_stream_class_borrow_event_context_field_type(
 440                 struct bt_stream_class *stream_class);
 441
 442 /**
 443 @brief  Returns the event context field type of the CTF IR stream class
 444         \p stream_class.
 445
 446 @param[in] stream_class Stream class of which to get the event context
 447                         field type.
 448 @returns                Event context field type of \p stream_class,
 449                         or \c NULL if \p stream_class has no event context field
 450                         type or on error.
 451
 452 @prenotnull{stream_class}
 453 @postrefcountsame{stream_class}
 454 @post <strong>On success, if the return value is a field type</strong>,
 455         its reference count is incremented.
 456
 457
 458 @sa bt_stream_class_set_event_context_field_type(): Sets the event
 459         context field type of a given stream class.
 460 */
 461 static inline
 462 struct bt_field_type *
 463 bt_stream_class_get_event_context_field_type(
 464                 struct bt_stream_class *stream_class)
 465 {
 466         return bt_get(bt_stream_class_borrow_event_context_field_type(
 467                 stream_class));
 468 }
 469
 470 /**
 471 @brief  Sets the event context field type of the CTF IR stream class
 472         \p stream_class to \p event_context_type, or unsets the current event
 473         context field type from \p stream_class.
 474
 475 If \p event_context_type is \c NULL, then this function unsets the current
 476 event context field type from \p stream_class, effectively making \p
 477 stream_class a stream class without a event context field type.
 478
 479 As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
 480 \p event_context_type \em must be a CTF IR structure field type object.
 481
 482 @param[in] stream_class         Stream class of which to set the packet
 483                                 context field type.
 484 @param[in] event_context_type   Event context field type, or \c NULL to unset
 485                                 the current event context field type.
 486 @returns                        0 on success, or a negative value on error.
 487
 488 @prenotnull{stream_class}
 489 @prehot{stream_class}
 490 @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
 491         structure field type.
 492 @postrefcountsame{stream_class}
 493 @post <strong>On success, if \p event_context_type is not \c NULL</strong>,
 494         the reference count of \p event_context_type is incremented.
 495
 496 @sa bt_stream_class_get_event_context_field_type(): Returns the event context
 497         field type of a given stream class.
 498 */
 499 extern int bt_stream_class_set_event_context_field_type(
 500                 struct bt_stream_class *stream_class,
 501                 struct bt_field_type *event_context_type);
 502
 503 /** @} */
 504
 505 /**
 506 @name Event class children functions
 507 @{
 508 */
 509
 510 /**
 511 @brief  Returns the number of event classes contained in the
 512         CTF IR stream class \p stream_class.
 513
 514 @param[in] stream_class Stream class of which to get the number
 515                         of children event classes.
 516 @returns                Number of children event classes
 517                         contained in \p stream_class, or
 518                         a negative value on error.
 519
 520 @prenotnull{stream_class}
 521 @postrefcountsame{stream_class}
 522 */
 523 extern int64_t bt_stream_class_get_event_class_count(
 524                 struct bt_stream_class *stream_class);
 525
 526 extern struct bt_event_class *bt_stream_class_borrow_event_class_by_index(
 527                 struct bt_stream_class *stream_class, uint64_t index);
 528
 529 /**
 530 @brief  Returns the event class at index \p index in the CTF IR stream
 531         class \p stream_class.
 532
 533 @param[in] stream_class Stream class of which to get the event class.
 534 @param[in] index        Index of the event class to find.
 535 @returns                Event class at index \p index, or \c NULL
 536                         on error.
 537
 538 @prenotnull{stream_class}
 539 @pre \p index is lesser than the number of event classes contained in the
 540         stream class \p stream_class (see
 541         bt_stream_class_get_event_class_count()).
 542 @postrefcountsame{stream_class}
 543 @postsuccessrefcountretinc
 544
 545 @sa bt_stream_class_get_event_class_by_id(): Finds an event class
 546         by ID.
 547 */
 548 static inline
 549 struct bt_event_class *bt_stream_class_get_event_class_by_index(
 550                 struct bt_stream_class *stream_class, uint64_t index)
 551 {
 552         return bt_get(bt_stream_class_borrow_event_class_by_index(stream_class,
 553                 index));
 554 }
 555
 556 extern struct bt_event_class *bt_stream_class_borrow_event_class_by_id(
 557                 struct bt_stream_class *stream_class, uint64_t id);
 558
 559 /**
 560 @brief  Returns the event class with ID \c id found in the CTF IR stream
 561         class \p stream_class.
 562
 563 @param[in] stream_class Stream class of which to get the event class.
 564 @param[in] id           ID of the event class to find.
 565 @returns                Event class with ID \p id, or \c NULL
 566                         on error.
 567
 568 @prenotnull{stream_class}
 569 @postrefcountsame{stream_class}
 570 @postsuccessrefcountretinc
 571 */
 572 static inline
 573 struct bt_event_class *bt_stream_class_get_event_class_by_id(
 574                 struct bt_stream_class *stream_class, uint64_t id)
 575 {
 576         return bt_get(bt_stream_class_borrow_event_class_by_id(stream_class,
 577                 id));
 578 }
 579
 580 /**
 581 @brief  Adds the CTF IR event class \p event_class to the
 582         CTF IR stream class \p stream_class.
 583
 584 On success, \p event_class becomes the child of \p stream_class.
 585
 586 You can only add a given event class to one stream class.
 587
 588 You can call this function even if \p stream_class is frozen. Adding
 589 event classes is the only operation that is permitted
 590 on a frozen stream class.
 591
 592 This function tries to resolve the needed
 593 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 594 types that are found anywhere in the context or payload field
 595 types of \p event_class. If any automatic resolving fails:
 596
 597 - If the needed field type should be found in one of the root field
 598   types of \p event_class or \p stream_class, this function fails.
 599 - If \p stream_class is the child of a
 600   \link ctfirtraceclass CTF IR trace class\endlink (it was added
 601   with bt_trace_add_stream_class()), this function fails.
 602 - If \p stream_class is not the child of a trace class yet, the
 603   automatic resolving is reported to the next call to
 604   bt_trace_add_stream_class() with \p stream_class.
 605
 606 @param[in] stream_class Stream class to which to add \p event_class.
 607 @param[in] event_class  Event class to add to \p stream_class.
 608 @returns                0 on success, or a negative value on error.
 609
 610 @prenotnull{stream_class}
 611 @prenotnull{event_class}
 612 @prehot{event_class}
 613 @postrefcountsame{stream_class}
 614 @postsuccessrefcountinc{event_class}
 615 @postsuccessfrozen{event_class}
 616 */
 617 extern int bt_stream_class_add_event_class(
 618                 struct bt_stream_class *stream_class,
 619                 struct bt_event_class *event_class);
 620
 621 /** @} */
 622
 623 /**
 624 @name Misc. function
 625 @{
 626 */
 627
 628 /**
 629 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 630         CTF IR stream class \p stream_class.
 631
 632 This function traverses the hierarchy of \p stream_class in pre-order
 633 and calls \p visitor on each element.
 634
 635 The stream class itself is visited first, and then all its children
 636 event classes.
 637
 638 @param[in] stream_class Stream class to visit.
 639 @param[in] visitor      Visiting function.
 640 @param[in] data         User data.
 641 @returns                0 on success, or a negative value on error.
 642
 643 @prenotnull{stream_class}
 644 @prenotnull{visitor}
 645 */
 646 extern int bt_stream_class_visit(struct bt_stream_class *stream_class,
 647                 bt_visitor visitor, void *data);
 648
 649 /** @} */
 650
 651 /** @} */
 652
 653 #ifdef __cplusplus
 654 }
 655 #endif
 656
 657 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */