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