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