include/babeltrace/ctf-ir/trace.h

   1 #ifndef BABELTRACE_CTF_IR_TRACE_H
   2 #define BABELTRACE_CTF_IR_TRACE_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Trace
   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 <babeltrace/ctf-ir/field-types.h>
  34 #include <babeltrace/ctf-ir/visitor.h>
  35 #include <babeltrace/values.h>
  36 #include <babeltrace/graph/notification.h>
  37 #include <stdint.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44 @defgroup ctfirtraceclass CTF IR trace class
  45 @ingroup ctfir
  46 @brief CTF IR trace class.
  47
  48 @code
  49 #include <babeltrace/ctf-ir/trace.h>
  50 @endcode
  51
  52 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
  53 traces.
  54
  55 You can obtain a trace class in two different modes:
  56
  57 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
  58   default, empty trace class.
  59 - <strong>CTF writer mode</strong>: use bt_ctf_writer_get_trace() to
  60   get the trace class created by a given CTF writer object.
  61
  62 A trace class has the following properties:
  63
  64 - A \b name.
  65 - A <strong>native byte order</strong>: all the
  66   \link ctfirfieldtypes field types\endlink eventually part of the trace
  67   class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
  68   "real" byte order.
  69 - A \b UUID.
  70 - An \b environment, which is a custom key-value mapping. Keys are
  71   strings and values can be strings or integers.
  72
  73 In the Babeltrace CTF IR system, a trace class contains zero or more
  74 \link ctfirstreamclass stream classes\endlink, and a stream class
  75 contains zero or more \link ctfireventclass event classes\endlink. You
  76 can add an event class to a stream class with
  77 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
  78 trace class with bt_ctf_trace_add_stream_class().
  79
  80 You can access the streams of a trace, that is, the streams which were
  81 created from the trace's stream classes with bt_ctf_stream_create(),
  82 with bt_ctf_trace_get_stream_by_index().
  83
  84 A trace class owns the <strong>trace packet header</strong>
  85 \link ctfirfieldtypes field type\endlink, which represents the
  86 \c trace.packet.header CTF scope. This field type describes the
  87 trace packet header fields of the traces that this trace class
  88 describes.
  89
  90 The trace packet header field type \em must be a structure field type as
  91 of Babeltrace \btversion.
  92
  93 As per the CTF specification, the trace packet header field type \em
  94 must contain a field named \c stream_id if the trace class contains more
  95 than one stream class.
  96
  97 As a reminder, here's the structure of a CTF packet:
  98
  99 @imgpacketstructure
 100
 101 A trace class also contains zero or more
 102 \link ctfirclockclass CTF IR clock classes\endlink.
 103
 104 @todo
 105 Elaborate about clock classes irt clock values.
 106
 107 As with any Babeltrace object, CTF IR trace class objects have
 108 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 109 counts</a>. See \ref refs to learn more about the reference counting
 110 management of Babeltrace objects.
 111
 112 The following functions \em freeze their trace class parameter on
 113 success:
 114
 115 - bt_ctf_trace_add_stream_class()
 116 - bt_ctf_writer_create_stream()
 117   (\link ctfwriter CTF writer\endlink mode only)
 118
 119 You cannot modify a frozen trace class: it is considered immutable,
 120 except for:
 121
 122 - Adding a stream class to it with
 123   bt_ctf_trace_add_stream_class().
 124 - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class().
 125 - \link refs Reference counting\endlink.
 126
 127 @sa ctfirstreamclass
 128 @sa ctfireventclass
 129 @sa ctfirclockclass
 130
 131 @file
 132 @brief CTF IR trace class type and functions.
 133 @sa ctfirtraceclass
 134
 135 @addtogroup ctfirtraceclass
 136 @{
 137 */
 138
 139 /**
 140 @struct bt_ctf_trace
 141 @brief A CTF IR trace class.
 142 @sa ctfirtraceclass
 143 */
 144 struct bt_ctf_trace;
 145 struct bt_ctf_stream;
 146 struct bt_ctf_stream_class;
 147 struct bt_ctf_clock_class;
 148
 149 /**
 150 @name Creation function
 151 @{
 152 */
 153
 154 /**
 155 @brief  Creates a default CTF IR trace class.
 156
 157 On success, the trace packet header field type of the created trace
 158 class is an empty structure field type. You can modify this default
 159 trace packet header field type after the trace class is created with
 160 bt_ctf_trace_get_packet_header_type() and
 161 bt_ctf_trace_set_packet_header_type().
 162
 163 The created trace class has the following initial properties:
 164
 165 - <strong>Name</strong>: none. You can set a name
 166   with bt_ctf_trace_set_name().
 167 - <strong>UUID</strong>: none. You can set a UUID with
 168   bt_ctf_trace_set_uuid().
 169 - <strong>Native byte order</strong>: #BT_CTF_BYTE_ORDER_NATIVE. You
 170   can set a native byte order with bt_ctf_trace_set_native_byte_order().
 171
 172   Note that you \em must set the native byte order if any field type
 173   contained in the created trace class, in its stream classes, or in
 174   its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE.
 175 - <strong>Environment</strong>: empty. You can add environment entries
 176   with bt_ctf_trace_set_environment_field(),
 177   bt_ctf_trace_set_environment_field_integer(), and
 178   bt_ctf_trace_set_environment_field_string().
 179
 180 @returns        Created trace class, or \c NULL on error.
 181
 182 @postsuccessrefcountret1
 183 */
 184 extern struct bt_ctf_trace *bt_ctf_trace_create(void);
 185
 186 /** @} */
 187
 188 /**
 189 @name Properties functions
 190 @{
 191 */
 192
 193 /**
 194 @brief  Returns the name of the CTF IR trace class \p trace_class.
 195
 196 On success, \p trace_class remains the sole owner of the returned
 197 string. The returned string is valid as long as \p trace_class exists
 198 and is not modified.
 199
 200 @param[in] trace_class  Trace class of which to get the name.
 201 @returns                Name of trace class \p trace_class, or
 202                         \c NULL if \p trace_class is unnamed or
 203                         on error.
 204
 205 @prenotnull{trace_class}
 206 @postrefcountsame{trace_class}
 207
 208 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
 209 */
 210 extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace *trace_class);
 211
 212 /**
 213 @brief  Sets the name of the CTF IR trace class \p trace_class
 214         to \p name.
 215
 216 @param[in] trace_class  Trace class of which to set the name.
 217 @param[in] name         Name of the trace class (copied on success).
 218 @returns                0 on success, or a negative value on error.
 219
 220 @prenotnull{trace_class}
 221 @prenotnull{name}
 222 @prehot{trace_class}
 223 @postrefcountsame{trace_class}
 224
 225 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
 226 */
 227 extern int bt_ctf_trace_set_name(struct bt_ctf_trace *trace_class,
 228                 const char *name);
 229
 230 /**
 231 @brief  Returns the native byte order of the CTF IR trace class
 232         \p trace_class.
 233
 234 @param[in] trace_class  Trace class of which to get the default byte
 235                         order.
 236 @returns                Native byte order of \p trace_class,
 237                         or #BT_CTF_BYTE_ORDER_UNKNOWN on error.
 238
 239 @prenotnull{trace_class}
 240 @postrefcountsame{trace_class}
 241
 242 @sa bt_ctf_trace_set_native_byte_order(): Sets the native byte order of
 243         a given trace class.
 244 */
 245 extern enum bt_ctf_byte_order bt_ctf_trace_get_native_byte_order(
 246                 struct bt_ctf_trace *trace_class);
 247
 248 /**
 249 @brief  Sets the native byte order of the CTF IR trace class
 250         \p trace_class to \p native_byte_order.
 251
 252 \p native_byte_order \em must be one of:
 253
 254 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
 255 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
 256 - #BT_CTF_BYTE_ORDER_NETWORK
 257
 258 @param[in] trace_class          Trace class of which to set the native byte
 259                                 order.
 260 @param[in] native_byte_order    Native byte order of the trace class.
 261 @returns                        0 on success, or a negative value on error.
 262
 263 @prenotnull{trace_class}
 264 @prehot{trace_class}
 265 @pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
 266         #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
 267         #BT_CTF_BYTE_ORDER_NETWORK.
 268 @postrefcountsame{trace_class}
 269
 270 @sa bt_ctf_trace_get_native_byte_order(): Returns the native byte order of a
 271         given trace class.
 272 */
 273 extern int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace *trace_class,
 274                 enum bt_ctf_byte_order native_byte_order);
 275
 276 /**
 277 @brief  Returns the UUID of the CTF IR trace class \p trace_class.
 278
 279 On success, the return value is an array of 16 bytes.
 280
 281 @param[in] trace_class  Trace class of which to get the UUID.
 282 @returns                UUID of trace class \p trace_class, or
 283                         \c NULL if \p trace_class has no UUID or on error.
 284
 285 @prenotnull{trace_class}
 286 @postrefcountsame{trace_class}
 287
 288 @sa bt_ctf_trace_set_uuid(): Sets the UUID of a given trace class.
 289 */
 290 extern const unsigned char *bt_ctf_trace_get_uuid(
 291                 struct bt_ctf_trace *trace_class);
 292
 293 /**
 294 @brief  Sets the UUID of the CTF IR trace class \p trace_class to
 295         \p uuid.
 296
 297 \p uuid \em must be an array of 16 bytes.
 298
 299 @param[in] trace_class          Trace class of which to set the UUID.
 300 @param[in] uuid                 UUID of the \p trace_class (copied on
 301                                 success).
 302 @returns                        0 on success, or a negative value on error.
 303
 304 @prenotnull{trace_class}
 305 @prenotnull{uuid}
 306 @prehot{trace_class}
 307 @pre \p uuid is an array of 16 bytes.
 308 @postrefcountsame{trace_class}
 309
 310 @sa bt_ctf_trace_get_uuid(): Returns the UUID of a given trace class.
 311 */
 312 extern int bt_ctf_trace_set_uuid(struct bt_ctf_trace *trace_class,
 313                 const unsigned char *uuid);
 314
 315 /**
 316 @brief  Returns the number of entries contained in the environment of
 317         the CTF IR trace class \p trace_class.
 318
 319 @param[in] trace_class  Trace class of which to get the number
 320                         of environment entries.
 321 @returns                Number of environment entries
 322                         contained in \p trace_class, or
 323                         a negative value on error.
 324
 325 @prenotnull{trace_class}
 326 @postrefcountsame{trace_class}
 327 */
 328 extern int64_t bt_ctf_trace_get_environment_field_count(
 329                 struct bt_ctf_trace *trace_class);
 330
 331 /**
 332 @brief  Returns the field name of the environment entry at index
 333         \p index in the CTF IR trace class \p trace_class.
 334
 335 On success, the returned string is valid as long as this trace class
 336 exists and is \em not modified. \p trace_class remains the sole owner of
 337 the returned string.
 338
 339 @param[in] trace_class  Trace class of which to get the name of the
 340                         environment entry at index \p index.
 341 @param[in] index        Index of environment entry to find.
 342 @returns                Name of the environment entry at index \p index
 343                         in \p trace_class, or \c NULL on error.
 344
 345 @prenotnull{trace_class}
 346 @pre \p index is lesser than the number of environment entries in
 347         \p trace_class (see bt_ctf_trace_get_environment_field_count()).
 348 @postrefcountsame{trace_class}
 349
 350 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
 351         environment entry by index.
 352 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 353         class's environment entry by name.
 354 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 355         class's environment entry.
 356 */
 357 extern const char *
 358 bt_ctf_trace_get_environment_field_name_by_index(
 359                 struct bt_ctf_trace *trace_class, uint64_t index);
 360
 361 /**
 362 @brief  Returns the value of the environment entry at index
 363         \p index in the CTF IR trace class \p trace_class.
 364
 365 @param[in] trace_class  Trace class of which to get the value of the
 366                         environment entry at index \p index.
 367 @param[in] index        Index of the environment entry to find.
 368 @returns                Value of the environment entry at index \p index
 369                         in \p trace_class, or \c NULL on error.
 370
 371 @prenotnull{trace_class}
 372 @pre \p index is lesser than the number of environment entries in
 373         \p trace_class (see bt_ctf_trace_get_environment_field_count()).
 374 @postrefcountsame{trace_class}
 375 @postsuccessrefcountretinc
 376
 377 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 378         class's environment entry by name.
 379 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 380         class's environment entry.
 381 */
 382 extern struct bt_value *
 383 bt_ctf_trace_get_environment_field_value_by_index(struct bt_ctf_trace *trace_class,
 384                 uint64_t index);
 385
 386 /**
 387 @brief  Returns the value of the environment entry named \p name
 388         in the CTF IR trace class \p trace_class.
 389
 390 @param[in] trace_class  Trace class of which to get the value of the
 391                         environment entry named \p name.
 392 @param[in] name         Name of the environment entry to find.
 393 @returns                Value of the environment entry named \p name
 394                         in \p trace_class, or \c NULL if there's no such
 395                         entry or on error.
 396
 397 @prenotnull{trace_class}
 398 @prenotnull{name}
 399 @postrefcountsame{trace_class}
 400 @postsuccessrefcountretinc
 401
 402 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
 403         environment entry by index.
 404 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 405         class's environment entry.
 406 */
 407 extern struct bt_value *
 408 bt_ctf_trace_get_environment_field_value_by_name(
 409                 struct bt_ctf_trace *trace_class, const char *name);
 410
 411 /**
 412 @brief  Sets the environment entry named \p name in the
 413         CTF IR trace class \p trace_class to \p value.
 414
 415 If an environment entry named \p name exists in \p trace_class, its
 416 value is first put, and then replaced by \p value.
 417
 418 @param[in] trace_class  Trace class of which to set the environment
 419                         entry.
 420 @param[in] name         Name of the environment entry to set (copied
 421                         on success).
 422 @param[in] value        Value of the environment entry named \p name.
 423 @returns                0 on success, or a negative value on error.
 424
 425 @prenotnull{trace_class}
 426 @prenotnull{name}
 427 @prenotnull{value}
 428 @prehot{trace_class}
 429 @pre \p value is an
 430         \link bt_value_integer_create() integer value object\endlink
 431         or a
 432         \link bt_value_string_create() string value object\endlink.
 433 @postrefcountsame{trace_class}
 434 @postsuccessrefcountinc{value}
 435
 436 @sa bt_ctf_trace_get_environment_field_value_by_index(): Finds a trace class's
 437         environment entry by index.
 438 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 439         class's environment entry by name.
 440 */
 441 extern int bt_ctf_trace_set_environment_field(
 442                 struct bt_ctf_trace *trace_class, const char *name,
 443                 struct bt_value *value);
 444
 445 /**
 446 @brief  Sets the environment entry named \p name in the
 447         CTF IR trace class \p trace_class to \p value.
 448
 449 If an environment entry named \p name exists in \p trace_class, its
 450 value is first put, and then replaced by a new
 451 \link bt_value_integer_create() integer value object\endlink
 452 containing \p value.
 453
 454 @param[in] trace_class  Trace class of which to set the environment
 455                         entry.
 456 @param[in] name         Name of the environment entry to set (copied
 457                         on success).
 458 @param[in] value        Value of the environment entry named \p name.
 459 @returns                0 on success, or a negative value on error.
 460
 461 @prenotnull{trace_class}
 462 @prenotnull{name}
 463 @prehot{trace_class}
 464 @postrefcountsame{trace_class}
 465
 466 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 467         class's environment entry.
 468 */
 469 extern int bt_ctf_trace_set_environment_field_integer(
 470                 struct bt_ctf_trace *trace_class, const char *name,
 471                 int64_t value);
 472
 473 /**
 474 @brief  Sets the environment entry named \p name in the
 475         CTF IR trace class \p trace_class to \p value.
 476
 477 If an environment entry named \p name exists in \p trace_class, its
 478 value is first put, and then replaced by a new
 479 \link bt_value_string_create() string value object\endlink
 480 containing \p value.
 481
 482 @param[in] trace_class  Trace class of which to set the environment
 483                         entry.
 484 @param[in] name         Name of the environment entry to set (copied
 485                         on success).
 486 @param[in] value        Value of the environment entry named \p name
 487                         (copied on success).
 488 @returns                0 on success, or a negative value on error.
 489
 490 @prenotnull{trace_class}
 491 @prenotnull{name}
 492 @prenotnull{value}
 493 @prehot{trace_class}
 494 @postrefcountsame{trace_class}
 495
 496 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 497         class's environment entry.
 498 */
 499 extern int bt_ctf_trace_set_environment_field_string(
 500                 struct bt_ctf_trace *trace_class, const char *name,
 501                 const char *value);
 502
 503 /** @} */
 504
 505 /**
 506 @name Contained field types functions
 507 @{
 508 */
 509
 510 /**
 511 @brief  Returns the packet header field type of the CTF IR trace class
 512         \p trace_class.
 513
 514 @param[in] trace_class  Trace class of which to get the packet
 515                         header field type.
 516 @returns                Packet header field type of \p trace_class,
 517                         or \c NULL if \p trace_class has no packet header field
 518                         type or on error.
 519
 520 @prenotnull{trace_class}
 521 @postrefcountsame{trace_class}
 522 @post <strong>On success, if the return value is a field type</strong>, its
 523         reference count is incremented.
 524
 525 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
 526         header field type of a given trace class.
 527 */
 528 extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
 529                 struct bt_ctf_trace *trace_class);
 530
 531 /**
 532 @brief  Sets the packet header field type of the CTF IR trace class
 533         \p trace_class to \p packet_header_type, or unsets the current packet
 534         header field type from \p trace_class.
 535
 536 If \p packet_header_type is \c NULL, then this function unsets the current
 537 packet header field type from \p trace_class, effectively making \p trace_class
 538 a trace without a packet header field type.
 539
 540 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
 541 \p packet_header_type \em must be a CTF IR structure field type object.
 542
 543 @param[in] trace_class          Trace class of which to set the packet
 544                                 header field type.
 545 @param[in] packet_header_type   Packet header field type, or \c NULL to unset
 546                                 the current packet header field type.
 547 @returns                        0 on success, or a negative value on error.
 548
 549 @prenotnull{trace_class}
 550 @prehot{trace_class}
 551 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
 552         structure field type.
 553 @postrefcountsame{trace_class}
 554 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
 555         the reference count of \p packet_header_type is incremented.
 556
 557 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
 558         header field type of a given trace class.
 559 */
 560 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace_class,
 561                 struct bt_ctf_field_type *packet_header_type);
 562
 563 /** @} */
 564
 565 /**
 566 @name Contained clock classes functions
 567 @{
 568 */
 569
 570 /**
 571 @brief  Returns the number of CTF IR clock classes contained in the
 572         CTF IR trace class \p trace_class.
 573
 574 @param[in] trace_class  Trace class of which to get the number
 575                         of contained clock classes.
 576 @returns                Number of contained clock classes
 577                         contained in \p trace_class, or a negative
 578                         value on error.
 579
 580 @prenotnull{trace_class}
 581 @postrefcountsame{trace_class}
 582 */
 583 extern int64_t bt_ctf_trace_get_clock_class_count(
 584                 struct bt_ctf_trace *trace_class);
 585
 586 /**
 587 @brief  Returns the CTF IR clock class at index \p index in the CTF
 588         IR trace class \p trace_class.
 589
 590 @param[in] trace_class  Trace class of which to get the clock class
 591                         contained at index \p index.
 592 @param[in] index        Index of the clock class to find in
 593                         \p trace_class.
 594 @returns                Clock class at index \p index in \p trace_class,
 595                         or \c NULL on error.
 596
 597 @prenotnull{trace_class}
 598 @pre \p index is lesser than the number of clock classes contained in
 599         the trace class \p trace_class (see
 600         bt_ctf_trace_get_clock_class_count()).
 601 @postrefcountsame{trace_class}
 602 @postsuccessrefcountretinc
 603
 604 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 605         in a given trace class.
 606 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 607 */
 608 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class_by_index(
 609                 struct bt_ctf_trace *trace_class, uint64_t index);
 610
 611 /**
 612 @brief  Returns the CTF IR clock class named \c name found in the CTF
 613         IR trace class \p trace_class.
 614
 615 @param[in] trace_class  Trace class of which to get the clock class
 616                         named \p name.
 617 @param[in] name         Name of the clock class to find in \p trace_class.
 618 @returns                Clock class named \p name in \p trace_class,
 619                         or \c NULL on error.
 620
 621 @prenotnull{trace_class}
 622 @prenotnull{name}
 623 @postrefcountsame{trace_class}
 624 @postsuccessrefcountretinc
 625
 626 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
 627         in a given trace class at a given index.
 628 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 629 */
 630 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class_by_name(
 631                 struct bt_ctf_trace *trace_class, const char *name);
 632
 633 /**
 634 @brief  Adds the CTF IR clock class \p clock_class to the CTF IR
 635         trace class \p trace_class.
 636
 637 On success, \p trace_class contains \p clock_class.
 638
 639 You can call this function even if \p trace_class or \p clock_class
 640 are frozen.
 641
 642 @param[in] trace_class  Trace class to which to add \p clock_class.
 643 @param[in] clock_class  Clock class to add to \p trace_class.
 644 @returns                0 on success, or a negative value on error.
 645
 646 @prenotnull{trace_class}
 647 @prenotnull{clock_class}
 648 @postrefcountsame{trace_class}
 649 @postsuccessrefcountinc{clock_class}
 650 @post <strong>On success, if \p trace_class is frozen</strong>,
 651         \p clock_class is frozen.
 652
 653 @sa bt_ctf_trace_get_clock_class_by_index(): Returns the clock class contained
 654         in a given trace class at a given index.
 655 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 656         in a given trace class.
 657 */
 658 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace *trace_class,
 659                 struct bt_ctf_clock_class *clock_class);
 660
 661 /** @} */
 662
 663 /**
 664 @name Stream class children functions
 665 @{
 666 */
 667
 668 /**
 669 @brief  Returns the number of stream classes contained in the
 670         CTF IR trace class \p trace_class.
 671
 672 @param[in] trace_class  Trace class of which to get the number
 673                         of children stream classes.
 674 @returns                Number of children stream classes
 675                         contained in \p trace_class, or a negative
 676                         value on error.
 677
 678 @prenotnull{trace_class}
 679 @postrefcountsame{trace_class}
 680 */
 681 extern int64_t bt_ctf_trace_get_stream_class_count(
 682                 struct bt_ctf_trace *trace_class);
 683
 684 /**
 685 @brief  Returns the stream class at index \p index in the CTF IR trace
 686         class \p trace_class.
 687
 688 @param[in] trace_class  Trace class of which to get the stream class.
 689 @param[in] index        Index of the stream class to find.
 690 @returns                Stream class at index \p index, or \c NULL
 691                         on error.
 692
 693 @prenotnull{trace_class}
 694 @pre \p index is lesser than the number of stream classes contained in
 695         the trace class \p trace_class (see
 696         bt_ctf_trace_get_stream_class_count()).
 697 @postrefcountsame{trace_class}
 698
 699 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 700 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
 701 */
 702 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_index(
 703                 struct bt_ctf_trace *trace_class, uint64_t index);
 704
 705 /**
 706 @brief  Returns the stream class with ID \c id found in the CTF IR
 707         trace class \p trace_class.
 708
 709 @param[in] trace_class  Trace class of which to get the stream class.
 710 @param[in] id           ID of the stream class to find.
 711 @returns                Stream class with ID \p id, or \c NULL
 712                         on error.
 713
 714 @prenotnull{trace_class}
 715 @postrefcountsame{trace_class}
 716 @postsuccessrefcountretinc
 717
 718 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
 719         in a given trace class at a given index.
 720 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
 721 */
 722 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id(
 723                 struct bt_ctf_trace *trace_class, uint64_t id);
 724
 725 /**
 726 @brief  Adds the CTF IR stream class \p stream_class to the
 727         CTF IR trace class \p trace_class.
 728
 729 On success, \p stream_class becomes the child of \p trace_class.
 730
 731 You can only add a given stream class to one trace class.
 732
 733 You can call this function even if \p trace_class is frozen.
 734
 735 This function tries to resolve the needed
 736 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 737 types that are found anywhere in the root field types of
 738 \p stream_class and of all its currently contained
 739 \link ctfireventclass CTF IR event classes\endlink. If any automatic
 740 resolving fails, then this function fails.
 741
 742 @param[in] trace_class  Trace class to which to add \p stream_class.
 743 @param[in] stream_class Stream class to add to \p trace_class.
 744 @returns                0 on success, or a negative value on error.
 745
 746 @prenotnull{trace_class}
 747 @prenotnull{stream_class}
 748 @postrefcountsame{trace_class}
 749 @postsuccessrefcountinc{stream_class}
 750 @postsuccessfrozen{stream_class}
 751
 752 @sa bt_ctf_trace_get_stream_class_by_index(): Returns the stream class contained
 753         in a given trace class at a given index.
 754 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 755 */
 756 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace_class,
 757                 struct bt_ctf_stream_class *stream_class);
 758
 759 /** @} */
 760
 761 /**
 762 @name Stream children functions
 763 @{
 764 */
 765
 766 /**
 767 @brief  Returns the number of streams contained in the CTF IR trace
 768         class \p trace_class.
 769
 770 @param[in] trace_class  Trace class of which to get the number
 771                         of children streams.
 772 @returns                Number of children streams
 773                         contained in \p trace_class, or a negative
 774                         value on error.
 775
 776 @prenotnull{trace_class}
 777 @postrefcountsame{trace_class}
 778 */
 779 extern int64_t bt_ctf_trace_get_stream_count(struct bt_ctf_trace *trace_class);
 780
 781 /**
 782 @brief  Returns the stream at index \p index in the CTF IR trace
 783         class \p trace_class.
 784
 785 @param[in] trace_class  Trace class of which to get the stream.
 786 @param[in] index        Index of the stream to find.
 787 @returns                Stream at index \p index, or \c NULL
 788                         on error.
 789
 790 @prenotnull{trace_class}
 791 @pre \p index is lesser than the number of streams contained in
 792         the trace class \p trace_class (see
 793         bt_ctf_trace_get_stream_count()).
 794 @postrefcountsame{trace_class}
 795 */
 796 extern struct bt_ctf_stream *bt_ctf_trace_get_stream_by_index(
 797                 struct bt_ctf_trace *trace_class, uint64_t index);
 798
 799 /** @} */
 800
 801 /**
 802 @name Misc. functions
 803 @{
 804 */
 805
 806 /**
 807 @brief  Returns whether or not the CTF IR trace class \p trace_class
 808         is static.
 809
 810 It is guaranteed that a static trace class will never contain new
 811 streams, stream classes, or clock classes. A static class is always
 812 frozen.
 813
 814 This function returns \c true if bt_ctf_trace_set_is_static() was
 815 previously called on it.
 816
 817 @param[in] trace_class  Trace class to check.
 818 @returns                \c true if \p trace_class is static,
 819
 820 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
 821 */
 822 extern bool bt_ctf_trace_is_static(struct bt_ctf_trace *trace_class);
 823
 824 /**
 825 @brief  Makes the CTF IR trace class \p trace_class static.
 826
 827 A static trace class is frozen and you cannot call any modifying
 828 function on it:
 829
 830 - bt_ctf_trace_add_stream_class()
 831 - bt_ctf_trace_add_clock_class()
 832
 833 You cannot create a stream with bt_ctf_stream_create() with any of the
 834 stream classes of a static trace class.
 835
 836 @param[in] trace_class  Trace class to make static.
 837 @returns                0 on success, or a negative value on error.
 838
 839 @prenotnull{trace_class}
 840 @postrefcountsame{trace_class}
 841 @postsuccessfrozen{trace_class}
 842
 843 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
 844         is static.
 845 */
 846 extern int bt_ctf_trace_set_is_static(struct bt_ctf_trace *trace_class);
 847
 848 /**
 849 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 850         CTF IR trace class \p trace_class.
 851
 852 This function traverses the hierarchy of \p trace_class in pre-order
 853 and calls \p visitor on each element.
 854
 855 The trace class itself is visited first, then, for each children stream
 856 class, the stream class itself, and all its children event classes.
 857
 858 @param[in] trace_class  Trace class to visit.
 859 @param[in] visitor      Visiting function.
 860 @param[in] data         User data.
 861 @returns                0 on success, or a negative value on error.
 862
 863 @prenotnull{trace_class}
 864 @prenotnull{visitor}
 865 */
 866 extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class,
 867                 bt_ctf_visitor visitor, void *data);
 868
 869 /** @} */
 870
 871 /** @} */
 872
 873 #ifdef __cplusplus
 874 }
 875 #endif
 876
 877 #endif /* BABELTRACE_CTF_IR_TRACE_H */