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