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