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