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 ctfirwriterstreamclass which documents additional CTF IR stream
  51 class functions exclusive to the CTF IR 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 ctfirwriter CTF IR 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 ctfirwriterstreamclass
 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 @postsuccessrefcountretinc
 191
 192 @sa bt_ctf_trace_add_stream_class(): Add a stream class to
 193         a trace class.
 194 */
 195 extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace(
 196                 struct bt_ctf_stream_class *stream_class);
 197
 198 /** @} */
 199
 200 /**
 201 @name Properties functions
 202 @{
 203 */
 204
 205 /**
 206 @brief  Returns the name of the CTF IR stream class \p stream_class.
 207
 208 On success, \p stream_class remains the sole owner of the returned
 209 string.
 210
 211 @param[in] stream_class Stream class of which to get the name.
 212 @returns                Name of stream class \p stream_class, or
 213                         \c NULL if \p stream_class is unnamed or
 214                         on error.
 215
 216 @prenotnull{stream_class}
 217 @postrefcountsame{stream_class}
 218
 219 @sa bt_ctf_stream_class_set_name(): Sets the name of a given
 220         stream class.
 221 */
 222 extern const char *bt_ctf_stream_class_get_name(
 223                 struct bt_ctf_stream_class *stream_class);
 224
 225 /**
 226 @brief  Sets the name of the CTF IR stream class
 227         \p stream_class to \p name.
 228
 229 \p name must be unique amongst the names of all the stream classes
 230 of the trace class to which you eventually add \p stream_class.
 231
 232 @param[in] stream_class Stream class of which to set the name.
 233 @param[in] name         Name of the stream class (copied on success).
 234 @returns                0 on success, or a negative value on error.
 235
 236 @prenotnull{stream_class}
 237 @prenotnull{name}
 238 @prehot{stream_class}
 239 @postrefcountsame{stream_class}
 240
 241 @sa bt_ctf_stream_class_get_name(): Returns the name of a given
 242         stream class.
 243 */
 244 extern int bt_ctf_stream_class_set_name(
 245                 struct bt_ctf_stream_class *stream_class, const char *name);
 246
 247 /**
 248 @brief  Returns the numeric ID of the CTF IR stream class \p stream_class.
 249
 250 @param[in] stream_class Stream class of which to get the numeric ID.
 251 @returns                ID of stream class \p stream_class, or a
 252                         negative value on error.
 253
 254 @prenotnull{stream_class}
 255 @postrefcountsame{stream_class}
 256
 257 @sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
 258         stream class.
 259 */
 260 extern int64_t bt_ctf_stream_class_get_id(
 261                 struct bt_ctf_stream_class *stream_class);
 262
 263 /**
 264 @brief  Sets the numeric ID of the CTF IR stream class
 265         \p stream_class to \p id.
 266
 267 \p id must be unique amongst the IDs of all the stream classes
 268 of the trace class to which you eventually add \p stream_class.
 269
 270 @param[in] stream_class Stream class of which to set the numeric ID.
 271 @param[in] id           ID of the stream class.
 272 @returns                0 on success, or a negative value on error.
 273
 274 @prenotnull{stream_class}
 275 @prehot{stream_class}
 276 @postrefcountsame{stream_class}
 277
 278 @sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
 279         stream class.
 280 */
 281 extern int bt_ctf_stream_class_set_id(
 282                 struct bt_ctf_stream_class *stream_class, uint32_t id);
 283
 284 /** @} */
 285
 286 /**
 287 @name Contained field types functions
 288 @{
 289 */
 290
 291 /**
 292 @brief  Returns the packet context field type of the CTF IR stream class
 293         \p stream_class.
 294
 295 @param[in] stream_class Stream class of which to get the packet
 296                         context field type.
 297 @returns                Packet context field type of \p stream_class,
 298                         or \c NULL on error.
 299
 300 @prenotnull{stream_class}
 301 @postsuccessrefcountretinc
 302
 303 @sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
 304         context field type of a given stream class.
 305 */
 306 extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(
 307                 struct bt_ctf_stream_class *stream_class);
 308
 309 /**
 310 @brief  Sets the packet context field type of the CTF IR stream class
 311         \p stream_class to \p packet_context_type.
 312
 313 As of Babeltrace \btversion, \p packet_context_type \em must be a
 314 CTF IR structure field type object.
 315
 316 @param[in] stream_class         Stream class of which to set the packet
 317                                 context field type.
 318 @param[in] packet_context_type  Packet context field type.
 319 @returns                        0 on success, or a negative value on error.
 320
 321 @prenotnull{stream_class}
 322 @prenotnull{packet_context_type}
 323 @prehot{stream_class}
 324 @preisstructft{packet_context_type}
 325 @postrefcountsame{stream_class}
 326 @postsuccessrefcountinc{packet_context_type}
 327
 328 @sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
 329         context field type of a given stream class.
 330 */
 331 extern int bt_ctf_stream_class_set_packet_context_type(
 332                 struct bt_ctf_stream_class *stream_class,
 333                 struct bt_ctf_field_type *packet_context_type);
 334
 335 /**
 336 @brief  Returns the event header field type of the CTF IR stream class
 337         \p stream_class.
 338
 339 @param[in] stream_class Stream class of which to get the event header
 340                         field type.
 341 @returns                Event header field type of \p stream_class,
 342                         or \c NULL on error.
 343
 344 @prenotnull{stream_class}
 345 @postsuccessrefcountretinc
 346
 347 @sa bt_ctf_stream_class_set_event_header_type(): Sets the event
 348         header field type of a given stream class.
 349 */
 350 extern struct bt_ctf_field_type *
 351 bt_ctf_stream_class_get_event_header_type(
 352                 struct bt_ctf_stream_class *stream_class);
 353
 354 /**
 355 @brief  Sets the event header field type of the CTF IR stream class
 356         \p stream_class to \p event_header_type.
 357
 358 As of Babeltrace \btversion, \p event_header_type \em must be a
 359 CTF IR structure field type object.
 360
 361 @param[in] stream_class         Stream class of which to set the event
 362                                 header field type.
 363 @param[in] event_header_type    Event header field type.
 364 @returns                        0 on success, or a negative value on error.
 365
 366 @prenotnull{stream_class}
 367 @prenotnull{event_header_type}
 368 @prehot{stream_class}
 369 @preisstructft{event_header_type}
 370 @postrefcountsame{stream_class}
 371 @postsuccessrefcountinc{event_header_type}
 372
 373 @sa bt_ctf_stream_class_get_event_header_type(): Returns the event
 374         header field type of a given stream class.
 375 */
 376 extern int bt_ctf_stream_class_set_event_header_type(
 377                 struct bt_ctf_stream_class *stream_class,
 378                 struct bt_ctf_field_type *event_header_type);
 379
 380 /**
 381 @brief  Returns the per-stream class event context field type of the
 382         CTF IR stream class \p stream_class.
 383
 384 @param[in] stream_class Stream class of which to get the per-stream
 385                         class event context field type.
 386 @returns                Per-stream class event context field type of
 387                         \p stream_class, or \c NULL on error.
 388
 389 @prenotnull{stream_class}
 390 @postsuccessrefcountretinc
 391
 392 @sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
 393         class event context field type of a given stream class.
 394 */
 395 extern struct bt_ctf_field_type *
 396 bt_ctf_stream_class_get_event_context_type(
 397                 struct bt_ctf_stream_class *stream_class);
 398
 399 /**
 400 @brief  Sets the per-stream class event context field type of the CTF
 401         IR stream class \p stream_class to \p event_context_type.
 402
 403 As of Babeltrace \btversion, \p event_context_type \em must be a
 404 CTF IR structure field type object.
 405
 406 @param[in] stream_class         Stream class of which to set the
 407                                 per-stream class event context
 408                                 field type.
 409 @param[in] event_context_type   Per-stream class event context context
 410                                 field type.
 411 @returns                        0 on success, or a negative value on error.
 412
 413 @prenotnull{stream_class}
 414 @prenotnull{event_context_type}
 415 @prehot{stream_class}
 416 @preisstructft{event_context_type}
 417 @postrefcountsame{stream_class}
 418 @postsuccessrefcountinc{event_context_type}
 419
 420 @sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
 421         class event context field type of a given stream class.
 422 */
 423 extern int bt_ctf_stream_class_set_event_context_type(
 424                 struct bt_ctf_stream_class *stream_class,
 425                 struct bt_ctf_field_type *event_context_type);
 426
 427 /** @} */
 428
 429 /**
 430 @name Event class children functions
 431 @{
 432 */
 433
 434 /**
 435 @brief  Returns the number of event classes contained in the
 436         CTF IR stream class \p stream_class.
 437
 438 @param[in] stream_class Stream class of which to get the number
 439                         of children event classes.
 440 @returns                Number of children event classes
 441                         contained in \p stream_class, or
 442                         a negative value on error.
 443
 444 @prenotnull{stream_class}
 445 @postrefcountsame{stream_class}
 446 */
 447 extern int bt_ctf_stream_class_get_event_class_count(
 448                 struct bt_ctf_stream_class *stream_class);
 449
 450 /**
 451 @brief  Returns the event class at index \p index in the CTF IR stream
 452         class \p stream_class.
 453
 454 @param[in] stream_class Stream class of which to get the event class.
 455 @param[in] index        Index of the event class to find.
 456 @returns                Event class at index \p index, or \c NULL
 457                         on error.
 458
 459 @prenotnull{stream_class}
 460 @pre \p index is lesser than the number of event classes contained in the
 461         stream class \p stream_class (see
 462         bt_ctf_stream_class_get_event_class_count()).
 463 @postrefcountsame{stream_class}
 464 @postsuccessrefcountretinc
 465
 466 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
 467         by ID.
 468 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
 469         by name.
 470 */
 471 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
 472                 struct bt_ctf_stream_class *stream_class, int index);
 473
 474 /**
 475 @brief  Returns the event class named \c name found in the CTF IR stream
 476         class \p stream_class.
 477
 478 @param[in] stream_class Stream class of which to get the event class.
 479 @param[in] name         Name of the event class to find.
 480 @returns                Event class named \p name, or \c NULL
 481                         on error.
 482
 483 @prenotnull{stream_class}
 484 @prenotnull{name}
 485 @postrefcountsame{stream_class}
 486 @postsuccessrefcountretinc
 487
 488 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
 489         by ID.
 490 */
 491 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
 492                 struct bt_ctf_stream_class *stream_class, const char *name);
 493
 494 /**
 495 @brief  Returns the event class with ID \c id found in the CTF IR stream
 496         class \p stream_class.
 497
 498 @param[in] stream_class Stream class of which to get the event class.
 499 @param[in] id           ID of the event class to find.
 500 @returns                Event class with ID \p id, or \c NULL
 501                         on error.
 502
 503 @prenotnull{stream_class}
 504 @postrefcountsame{stream_class}
 505 @postsuccessrefcountretinc
 506
 507 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
 508         by name.
 509 */
 510 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
 511                 struct bt_ctf_stream_class *stream_class, uint32_t id);
 512
 513 /**
 514 @brief  Adds the CTF IR event class \p event_class to the
 515         CTF IR stream class \p stream_class.
 516
 517 On success, \p event_class becomes the child of \p stream_class.
 518
 519 You can only add a given event class to one stream class.
 520
 521 You can call this function even if \p stream_class is frozen. Adding
 522 event classes is the only operation that is permitted
 523 on a frozen stream class.
 524
 525 @param[in] stream_class Stream class to which to add \p event_class.
 526 @param[in] event_class  Event class to add to \p stream_class.
 527 @returns                0 on success, or a negative value on error.
 528
 529 @prenotnull{stream_class}
 530 @prenotnull{event_class}
 531 @prehot{event_class}
 532 @postrefcountsame{stream_class}
 533 @postsuccessrefcountinc{event_class}
 534 @postsuccessfrozen{event_class}
 535 */
 536 extern int bt_ctf_stream_class_add_event_class(
 537                 struct bt_ctf_stream_class *stream_class,
 538                 struct bt_ctf_event_class *event_class);
 539
 540 /** @} */
 541
 542 /**
 543 @name Misc. function
 544 @{
 545 */
 546
 547 /**
 548 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 549         CTF IR stream class \p stream_class.
 550
 551 This function traverses the hierarchy of \p stream_class in pre-order
 552 and calls \p visitor on each element.
 553
 554 The stream class itself is visited first, and then all its children
 555 event classes.
 556
 557 @param[in] stream_class Stream class to visit.
 558 @param[in] visitor      Visiting function.
 559 @param[in] data         User data.
 560 @returns                0 on success, or a negative value on error.
 561
 562 @prenotnull{stream_class}
 563 @prenotnull{visitor}
 564 */
 565 extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class,
 566                 bt_ctf_visitor visitor, void *data);
 567
 568 /** @} */
 569
 570 /** @} */
 571
 572 // TODO: document for writer
 573 extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
 574                 struct bt_ctf_stream_class *stream_class);
 575
 576 #ifdef __cplusplus
 577 }
 578 #endif
 579
 580 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */