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