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