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 an empty CTF IR stream class named \p name, or an
 150         unnamed empty stream class if \p name is \c NULL.
 151
 152 On success, the packet context, event header, and event context field
 153 types are empty structure field types. You can modify those default
 154 field types after the stream class is created with
 155 bt_stream_class_set_packet_context_type(),
 156 bt_stream_class_set_event_header_type(), and
 157 bt_stream_class_set_event_context_type().
 158
 159 @param[in] name Name of the stream class to create (copied on success),
 160                 or \c NULL to create an unnamed stream class.
 161 @returns        Created empty stream class, or \c NULL on error.
 162
 163 @postsuccessrefcountret1
 164
 165 @sa bt_stream_class_create(): Creates a default stream class.
 166 */
 167 extern struct bt_stream_class *bt_stream_class_create_empty(
 168                 const char *name);
 169
 170 /**
 171 @brief  Creates a default CTF IR stream class named \p name, or a
 172         default unnamed stream class if \p name is \c NULL.
 173
 174 On success, the packet context field type of the created stream class
 175 has the following fields:
 176
 177 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
 178 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
 179 - <code>content_size</code>: a 64-bit unsigned integer field type.
 180 - <code>packet_size</code>: a 64-bit unsigned integer field type.
 181 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
 182
 183 On success, the event header field type of the created stream class
 184 has the following fields:
 185
 186 - <code>code</code>: a 32-bit unsigned integer field type.
 187 - <code>timestamp</code>: a 64-bit unsigned integer field type.
 188
 189 You can modify those default field types after the stream class is
 190 created with bt_stream_class_set_packet_context_type() and
 191 bt_stream_class_set_event_header_type().
 192
 193 @param[in] name Name of the stream class to create (copied on success),
 194                 or \c NULL to create an unnamed stream class.
 195 @returns        Created default stream class, or \c NULL on error.
 196
 197 @postsuccessrefcountret1
 198
 199 @sa bt_stream_class_create_empty(): Creates an empty stream class.
 200 */
 201 extern struct bt_stream_class *bt_stream_class_create(const char *name);
 202
 203 /**
 204 @brief  Returns the parent CTF IR trace class of the CTF IR stream
 205         class \p stream_class.
 206
 207 It is possible that the stream class was not added to a trace class
 208 yet, in which case this function returns \c NULL. You can add a
 209 stream class to a trace class with
 210 bt_trace_add_stream_class().
 211
 212 @param[in] stream_class Stream class of which to get the parent
 213                         trace class.
 214 @returns                Parent trace class of \p stream_class,
 215                         or \c NULL if \p stream_class was not
 216                         added to a trace class yet or on error.
 217
 218 @prenotnull{stream_class}
 219 @postrefcountsame{stream_class}
 220 @postsuccessrefcountretinc
 221
 222 @sa bt_trace_add_stream_class(): Add a stream class to
 223         a trace class.
 224 */
 225 extern struct bt_trace *bt_stream_class_get_trace(
 226                 struct bt_stream_class *stream_class);
 227
 228 /** @} */
 229
 230 /**
 231 @name Properties functions
 232 @{
 233 */
 234
 235 /**
 236 @brief  Returns the name of the CTF IR stream class \p stream_class.
 237
 238 On success, \p stream_class remains the sole owner of the returned
 239 string.
 240
 241 @param[in] stream_class Stream class of which to get the name.
 242 @returns                Name of stream class \p stream_class, or
 243                         \c NULL if \p stream_class is unnamed or
 244                         on error.
 245
 246 @prenotnull{stream_class}
 247 @postrefcountsame{stream_class}
 248
 249 @sa bt_stream_class_set_name(): Sets the name of a given
 250         stream class.
 251 */
 252 extern const char *bt_stream_class_get_name(
 253                 struct bt_stream_class *stream_class);
 254
 255 /**
 256 @brief  Sets the name of the CTF IR stream class
 257         \p stream_class to \p name, or resets the name of
 258         \p stream_class.
 259
 260 If \p name is not \c NULL, it must be unique amongst the names of all
 261 the stream classes of the trace class to which you eventually add
 262 \p stream_class.
 263
 264 @param[in] stream_class Stream class of which to set the name.
 265 @param[in] name         Name of the stream class (copied on success), or
 266                         \c NULL to reset the name of \p stream_class
 267                         (make it unnamed).
 268 @returns                0 on success, or a negative value on error.
 269
 270 @prenotnull{stream_class}
 271 @prehot{stream_class}
 272 @postrefcountsame{stream_class}
 273
 274 @sa bt_stream_class_get_name(): Returns the name of a given
 275         stream class.
 276 */
 277 extern int bt_stream_class_set_name(
 278                 struct bt_stream_class *stream_class, const char *name);
 279
 280 /**
 281 @brief  Returns the numeric ID of the CTF IR stream class \p stream_class.
 282
 283 @param[in] stream_class Stream class of which to get the numeric ID.
 284 @returns                ID of stream class \p stream_class, or a
 285                         negative value on error.
 286
 287 @prenotnull{stream_class}
 288 @postrefcountsame{stream_class}
 289
 290 @sa bt_stream_class_set_id(): Sets the numeric ID of a given
 291         stream class.
 292 */
 293 extern int64_t bt_stream_class_get_id(
 294                 struct bt_stream_class *stream_class);
 295
 296 /**
 297 @brief  Sets the numeric ID of the CTF IR stream class
 298         \p stream_class to \p id.
 299
 300 \p id must be unique amongst the IDs of all the stream classes
 301 of the trace class to which you eventually add \p stream_class.
 302
 303 @param[in] stream_class Stream class of which to set the numeric ID.
 304 @param[in] id           ID of the stream class.
 305 @returns                0 on success, or a negative value on error.
 306
 307 @prenotnull{stream_class}
 308 @prehot{stream_class}
 309 @pre \p id is lesser than or equal to 9223372036854775807 (\c INT64_MAX).
 310 @postrefcountsame{stream_class}
 311
 312 @sa bt_stream_class_get_id(): Returns the numeric ID of a given
 313         stream class.
 314 */
 315 extern int bt_stream_class_set_id(
 316                 struct bt_stream_class *stream_class, uint64_t id);
 317
 318 /** @} */
 319
 320 /**
 321 @name Contained field types functions
 322 @{
 323 */
 324
 325 /**
 326 @brief  Returns the packet context field type of the CTF IR stream class
 327         \p stream_class.
 328
 329 @param[in] stream_class Stream class of which to get the packet
 330                         context field type.
 331 @returns                Packet context field type of \p stream_class,
 332                         or \c NULL if \p stream_class has no packet context
 333                         field type or on error.
 334
 335 @prenotnull{stream_class}
 336 @postrefcountsame{stream_class}
 337 @post <strong>On success, if the return value is a field type</strong>, its
 338         reference count is incremented.
 339
 340 @sa bt_stream_class_set_packet_context_type(): Sets the packet
 341         context field type of a given stream class.
 342 */
 343 extern struct bt_field_type *bt_stream_class_get_packet_context_type(
 344                 struct bt_stream_class *stream_class);
 345
 346 /**
 347 @brief  Sets the packet context field type of the CTF IR stream class
 348         \p stream_class to \p packet_context_type, or unsets the current packet
 349         context field type from \p stream_class.
 350
 351 If \p packet_context_type is \c NULL, then this function unsets the current
 352 packet context field type from \p stream_class, effectively making
 353 \p stream_class a stream class without a packet context field type.
 354
 355 As of Babeltrace \btversion, if \p packet_context_type is not \c NULL,
 356 \p packet_context_type \em must be a CTF IR structure field type object.
 357
 358 @param[in] stream_class         Stream class of which to set the packet
 359                                 context field type.
 360 @param[in] packet_context_type  Packet context field type, or \c NULL to unset
 361                                 the current packet context field type.
 362 @returns                        0 on success, or a negative value on error.
 363
 364 @prenotnull{stream_class}
 365 @prehot{stream_class}
 366 @pre <strong>\p packet_context_type, if not \c NULL</strong>, is a CTF IR
 367         structure field type.
 368 @postrefcountsame{stream_class}
 369 @post <strong>On success, if \p packet_context_type is not \c NULL</strong>,
 370         the reference count of \p packet_context_type is incremented.
 371
 372 @sa bt_stream_class_get_packet_context_type(): Returns the packet
 373         context field type of a given stream class.
 374 */
 375 extern int bt_stream_class_set_packet_context_type(
 376                 struct bt_stream_class *stream_class,
 377                 struct bt_field_type *packet_context_type);
 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_type(): Sets the event
 395         header field type of a given stream class.
 396 */
 397 extern struct bt_field_type *
 398 bt_stream_class_get_event_header_type(
 399                 struct bt_stream_class *stream_class);
 400
 401 /**
 402 @brief  Sets the event header field type of the CTF IR stream class
 403         \p stream_class to \p event_header_type, or unsets the current event
 404         header field type from \p stream_class.
 405
 406 If \p event_header_type is \c NULL, then this function unsets the current
 407 event header field type from \p stream_class, effectively making \p stream_class
 408 a stream class without a event header field type.
 409
 410 As of Babeltrace \btversion, if \p event_header_type is not \c NULL,
 411 \p event_header_type \em must be a CTF IR structure field type object.
 412
 413 @param[in] stream_class         Stream class of which to set the event
 414                                 header field type.
 415 @param[in] event_header_type    Event header field type, or \c NULL to unset
 416                                 the current event header field type.
 417 @returns                        0 on success, or a negative value on error.
 418
 419 @prenotnull{stream_class}
 420 @prehot{stream_class}
 421 @pre <strong>\p event_header_type, if not \c NULL</strong>, is a CTF IR
 422         structure field type.
 423 @postrefcountsame{stream_class}
 424 @post <strong>On success, if \p event_header_type is not \c NULL</strong>,
 425         the reference count of \p event_header_type is incremented.
 426
 427 @sa bt_stream_class_get_event_header_type(): Returns the event
 428         header field type of a given stream class.
 429 */
 430 extern int bt_stream_class_set_event_header_type(
 431                 struct bt_stream_class *stream_class,
 432                 struct bt_field_type *event_header_type);
 433
 434 /**
 435 @brief  Returns the event context field type of the CTF IR stream class
 436         \p stream_class.
 437
 438 @param[in] stream_class Stream class of which to get the event context
 439                         field type.
 440 @returns                Event context field type of \p stream_class,
 441                         or \c NULL if \p stream_class has no event context field
 442                         type or on error.
 443
 444 @prenotnull{stream_class}
 445 @postrefcountsame{stream_class}
 446 @post <strong>On success, if the return value is a field type</strong>,
 447         its reference count is incremented.
 448
 449
 450 @sa bt_stream_class_set_event_context_type(): Sets the event
 451         context field type of a given stream class.
 452 */
 453 extern struct bt_field_type *
 454 bt_stream_class_get_event_context_type(
 455                 struct bt_stream_class *stream_class);
 456
 457 /**
 458 @brief  Sets the event context field type of the CTF IR stream class
 459         \p stream_class to \p event_context_type, or unsets the current event
 460         context field type from \p stream_class.
 461
 462 If \p event_context_type is \c NULL, then this function unsets the current
 463 event context field type from \p stream_class, effectively making \p
 464 stream_class a stream class without a event context field type.
 465
 466 As of Babeltrace \btversion, if \p event_context_type is not \c NULL,
 467 \p event_context_type \em must be a CTF IR structure field type object.
 468
 469 @param[in] stream_class         Stream class of which to set the packet
 470                                 context field type.
 471 @param[in] event_context_type   Event context field type, or \c NULL to unset
 472                                 the current event context field type.
 473 @returns                        0 on success, or a negative value on error.
 474
 475 @prenotnull{stream_class}
 476 @prehot{stream_class}
 477 @pre <strong>\p event_context_type, if not \c NULL</strong>, is a CTF IR
 478         structure field type.
 479 @postrefcountsame{stream_class}
 480 @post <strong>On success, if \p event_context_type is not \c NULL</strong>,
 481         the reference count of \p event_context_type is incremented.
 482
 483 @sa bt_stream_class_get_event_context_type(): Returns the event context
 484         field type of a given stream class.
 485 */
 486 extern int bt_stream_class_set_event_context_type(
 487                 struct bt_stream_class *stream_class,
 488                 struct bt_field_type *event_context_type);
 489
 490 /** @} */
 491
 492 /**
 493 @name Event class children functions
 494 @{
 495 */
 496
 497 /**
 498 @brief  Returns the number of event classes contained in the
 499         CTF IR stream class \p stream_class.
 500
 501 @param[in] stream_class Stream class of which to get the number
 502                         of children event classes.
 503 @returns                Number of children event classes
 504                         contained in \p stream_class, or
 505                         a negative value on error.
 506
 507 @prenotnull{stream_class}
 508 @postrefcountsame{stream_class}
 509 */
 510 extern int64_t bt_stream_class_get_event_class_count(
 511                 struct bt_stream_class *stream_class);
 512
 513 /**
 514 @brief  Returns the event class at index \p index 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] index        Index of the event class to find.
 519 @returns                Event class at index \p index, or \c NULL
 520                         on error.
 521
 522 @prenotnull{stream_class}
 523 @pre \p index is lesser than the number of event classes contained in the
 524         stream class \p stream_class (see
 525         bt_stream_class_get_event_class_count()).
 526 @postrefcountsame{stream_class}
 527 @postsuccessrefcountretinc
 528
 529 @sa bt_stream_class_get_event_class_by_id(): Finds an event class
 530         by ID.
 531 */
 532 extern struct bt_event_class *bt_stream_class_get_event_class_by_index(
 533                 struct bt_stream_class *stream_class, uint64_t index);
 534
 535 /**
 536 @brief  Returns the event class with ID \c id found in the CTF IR stream
 537         class \p stream_class.
 538
 539 @param[in] stream_class Stream class of which to get the event class.
 540 @param[in] id           ID of the event class to find.
 541 @returns                Event class with ID \p id, or \c NULL
 542                         on error.
 543
 544 @prenotnull{stream_class}
 545 @postrefcountsame{stream_class}
 546 @postsuccessrefcountretinc
 547 */
 548 extern struct bt_event_class *bt_stream_class_get_event_class_by_id(
 549                 struct bt_stream_class *stream_class, uint64_t id);
 550
 551 /**
 552 @brief  Adds the CTF IR event class \p event_class to the
 553         CTF IR stream class \p stream_class.
 554
 555 On success, \p event_class becomes the child of \p stream_class.
 556
 557 You can only add a given event class to one stream class.
 558
 559 You can call this function even if \p stream_class is frozen. Adding
 560 event classes is the only operation that is permitted
 561 on a frozen stream class.
 562
 563 This function tries to resolve the needed
 564 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 565 types that are found anywhere in the context or payload field
 566 types of \p event_class. If any automatic resolving fails:
 567
 568 - If the needed field type should be found in one of the root field
 569   types of \p event_class or \p stream_class, this function fails.
 570 - If \p stream_class is the child of a
 571   \link ctfirtraceclass CTF IR trace class\endlink (it was added
 572   with bt_trace_add_stream_class()), this function fails.
 573 - If \p stream_class is not the child of a trace class yet, the
 574   automatic resolving is reported to the next call to
 575   bt_trace_add_stream_class() with \p stream_class.
 576
 577 @param[in] stream_class Stream class to which to add \p event_class.
 578 @param[in] event_class  Event class to add to \p stream_class.
 579 @returns                0 on success, or a negative value on error.
 580
 581 @prenotnull{stream_class}
 582 @prenotnull{event_class}
 583 @prehot{event_class}
 584 @postrefcountsame{stream_class}
 585 @postsuccessrefcountinc{event_class}
 586 @postsuccessfrozen{event_class}
 587 */
 588 extern int bt_stream_class_add_event_class(
 589                 struct bt_stream_class *stream_class,
 590                 struct bt_event_class *event_class);
 591
 592 /** @} */
 593
 594 /**
 595 @name Misc. function
 596 @{
 597 */
 598
 599 /**
 600 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 601         CTF IR stream class \p stream_class.
 602
 603 This function traverses the hierarchy of \p stream_class in pre-order
 604 and calls \p visitor on each element.
 605
 606 The stream class itself is visited first, and then all its children
 607 event classes.
 608
 609 @param[in] stream_class Stream class to visit.
 610 @param[in] visitor      Visiting function.
 611 @param[in] data         User data.
 612 @returns                0 on success, or a negative value on error.
 613
 614 @prenotnull{stream_class}
 615 @prenotnull{visitor}
 616 */
 617 extern int bt_stream_class_visit(struct bt_stream_class *stream_class,
 618                 bt_visitor visitor, void *data);
 619
 620 /** @} */
 621
 622 /** @} */
 623
 624 /* Pre-2.0 CTF writer compatibility */
 625 #define bt_ctf_stream_class bt_stream_class
 626 #define bt_ctf_stream_class_create bt_stream_class_create
 627 #define bt_ctf_stream_class_add_event_class bt_stream_class_add_event_class
 628 #define bt_ctf_stream_class_get_packet_context_type bt_stream_class_get_packet_context_type
 629
 630 #ifdef __cplusplus
 631 }
 632 #endif
 633
 634 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */