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