include/babeltrace/ctf-ir/stream-class.h

   1 #ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
   2 #define BABELTRACE_CTF_IR_STREAM_CLASS_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream Class
   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 <stdint.h>
  34 #include <babeltrace/ctf-ir/visitor.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41 @defgroup ctfirstreamclass CTF IR stream class
  42 @ingroup ctfir
  43 @brief CTF IR stream class.
  44
  45 @note
  46 See \ref ctfirwriterstreamclass which documents additional CTF IR stream
  47 class functions exclusive to the CTF IR writer mode.
  48
  49 A CTF IR <strong><em>stream class</em></strong> is a template that you
  50 can use to create concrete \link ctfirstream CTF IR streams\endlink.
  51
  52 A stream class has the following properties, both of which \em must
  53 be unique amongst all the stream classes contained in the same
  54 \link ctfirtraceclass CTF IR trace class\endlink:
  55
  56 - A \b name.
  57 - A numeric \b ID.
  58
  59 In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
  60 contains zero or more stream classes,
  61 and a stream class contains zero or more
  62 \link ctfireventclass event classes\endlink.
  63 You can add an event class
  64 to a stream class with bt_ctf_stream_class_add_event_class().
  65 You can add a stream class to a trace class with
  66 bt_ctf_trace_add_stream_class().
  67
  68 A stream class owns three \link ctfirfieldtypes field types\endlink:
  69
  70 - An optional <strong>stream packet context</strong> field type, which
  71   represents the \c stream.packet.context CTF scope.
  72 - An optional <strong>stream event header</strong> field type, which
  73   represents the \c stream.event.header CTF scope.
  74 - An optional <strong>stream event context</strong> field type, which
  75   represents the \c stream.event.context CTF scope.
  76
  77 Those three field types \em must be structure field types as of
  78 Babeltrace \btversion.
  79
  80 As per the CTF specification, the event header field type \em must
  81 contain a field named \c id if the stream class contains more than one
  82 event class.
  83
  84 As a reminder, here's the structure of a CTF packet:
  85
  86 @imgpacketstructure
  87
  88 Before you can create a stream from a stream class with
  89 bt_ctf_stream_create(), you \em must add the prepared stream class to a
  90 trace class by calling bt_ctf_trace_add_stream_class().
  91
  92 As with any Babeltrace object, CTF IR stream class objects have
  93 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  94 counts</a>. See \ref refs to learn more about the reference counting
  95 management of Babeltrace objects.
  96
  97 The following functions \em freeze their stream class parameter on
  98 success:
  99
 100 - bt_ctf_trace_add_stream_class()
 101 - bt_ctf_event_create()
 102 - bt_ctf_writer_create_stream()
 103   (\link ctfirwriter CTF IR writer\endlink mode only)
 104
 105 You cannot modify a frozen stream class: it is considered immutable,
 106 except for:
 107
 108 - Adding an event class to it with
 109   bt_ctf_stream_class_add_event_class().
 110 - \link refs Reference counting\endlink.
 111
 112 @sa ctfirstream
 113 @sa ctfireventclass
 114 @sa ctfirtraceclass
 115 @sa ctfirwriterstreamclass
 116
 117 @file
 118 @brief CTF IR stream class type and functions.
 119 @sa ctfirstreamclass
 120
 121 @addtogroup ctfirstreamclass
 122 @{
 123 */
 124
 125 /**
 126 @struct bt_ctf_stream_class
 127 @brief A CTF IR stream class.
 128 @sa ctfirstreamclass
 129 */
 130 struct bt_ctf_stream_class;
 131 struct bt_ctf_event_class;
 132 struct bt_ctf_clock;
 133
 134 /**
 135 @name Creation and parent access functions
 136 @{
 137 */
 138
 139 /**
 140 @brief  Creates a default CTF IR stream class named \p name, or a
 141         default unnamed stream class if \p name is \c NULL.
 142
 143 On success, the packet context field type of the created stream class
 144 has the following fields:
 145
 146 - <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
 147 - <code>timestamp_end</code>: a 64-bit unsigned integer field type.
 148 - <code>content_size</code>: a 64-bit unsigned integer field type.
 149 - <code>packet_size</code>: a 64-bit unsigned integer field type.
 150 - <code>events_discarded</code>: a 64-bit unsigned integer field type.
 151
 152 On success, the event header field type of the created stream class
 153 has the following fields:
 154
 155 - <code>code</code>: a 32-bit unsigned integer field type.
 156 - <code>timestamp</code>: a 64-bit unsigned integer field type.
 157
 158 You can modify those default field types after the stream class is
 159 created with bt_ctf_stream_class_set_packet_context_type() and
 160 bt_ctf_stream_class_set_event_header_type().
 161
 162 @param[in] name Name of the stream class to create (can be \c NULL to
 163                 create an unnamed stream class).
 164 @returns        Created stream class, or \c NULL on error.
 165
 166 @postsuccessrefcountret1
 167 */
 168 extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name);
 169
 170 /**
 171 @brief  Returns the parent CTF IR trace class of the CTF IR stream
 172         class \p stream_class.
 173
 174 It is possible that the stream class was not added to a trace class
 175 yet, in which case this function returns \c NULL. You can add a
 176 stream class to a trace class with
 177 bt_ctf_trace_add_stream_class().
 178
 179 @param[in] stream_class Stream class of which to get the parent
 180                         trace class.
 181 @returns                Parent trace class of \p stream_class,
 182                         or \c NULL if \p stream_class was not
 183                         added to a trace class yet or on error.
 184
 185 @prenotnull{stream_class}
 186 @postsuccessrefcountretinc
 187
 188 @sa bt_ctf_trace_add_stream_class(): Add a stream class to
 189         a trace class.
 190 */
 191 extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace(
 192                 struct bt_ctf_stream_class *stream_class);
 193
 194 /** @} */
 195
 196 /**
 197 @name Properties functions
 198 @{
 199 */
 200
 201 /**
 202 @brief  Returns the name of the CTF IR stream class \p stream_class.
 203
 204 On success, \p stream_class remains the sole owner of the returned
 205 string.
 206
 207 @param[in] stream_class Stream class of which to get the name.
 208 @returns                Name of stream class \p stream_class, or
 209                         \c NULL if \p stream_class is unnamed or
 210                         on error.
 211
 212 @prenotnull{stream_class}
 213 @postrefcountsame{stream_class}
 214
 215 @sa bt_ctf_stream_class_set_name(): Sets the name of a given
 216         stream class.
 217 */
 218 extern const char *bt_ctf_stream_class_get_name(
 219                 struct bt_ctf_stream_class *stream_class);
 220
 221 /**
 222 @brief  Sets the name of the CTF IR stream class
 223         \p stream_class to \p name.
 224
 225 \p name must be unique amongst the names of all the stream classes
 226 of the trace class to which you eventually add \p stream_class.
 227
 228 @param[in] stream_class Stream class of which to set the name.
 229 @param[in] name         Name of the stream class (copied on success).
 230 @returns                0 on success, or a negative value on error.
 231
 232 @prenotnull{stream_class}
 233 @prenotnull{name}
 234 @prehot{stream_class}
 235 @postrefcountsame{stream_class}
 236
 237 @sa bt_ctf_stream_class_get_name(): Returns the name of a given
 238         stream class.
 239 */
 240 extern int bt_ctf_stream_class_set_name(
 241                 struct bt_ctf_stream_class *stream_class, const char *name);
 242
 243 /**
 244 @brief  Returns the numeric ID of the CTF IR stream class \p stream_class.
 245
 246 @param[in] stream_class Stream class of which to get the numeric ID.
 247 @returns                ID of stream class \p stream_class, or a
 248                         negative value on error.
 249
 250 @prenotnull{stream_class}
 251 @postrefcountsame{stream_class}
 252
 253 @sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
 254         stream class.
 255 */
 256 extern int64_t bt_ctf_stream_class_get_id(
 257                 struct bt_ctf_stream_class *stream_class);
 258
 259 /**
 260 @brief  Sets the numeric ID of the CTF IR stream class
 261         \p stream_class to \p id.
 262
 263 \p id must be unique amongst the IDs of all the stream classes
 264 of the trace class to which you eventually add \p stream_class.
 265
 266 @param[in] stream_class Stream class of which to set the numeric ID.
 267 @param[in] id           ID of the stream class.
 268 @returns                0 on success, or a negative value on error.
 269
 270 @prenotnull{stream_class}
 271 @prehot{stream_class}
 272 @postrefcountsame{stream_class}
 273
 274 @sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
 275         stream class.
 276 */
 277 extern int bt_ctf_stream_class_set_id(
 278                 struct bt_ctf_stream_class *stream_class, uint32_t id);
 279
 280 /** @} */
 281
 282 /**
 283 @name Contained field types functions
 284 @{
 285 */
 286
 287 /**
 288 @brief  Returns the packet context field type of the CTF IR stream class
 289         \p stream_class.
 290
 291 @param[in] stream_class Stream class of which to get the packet
 292                         context field type.
 293 @returns                Packet context field type of \p stream_class,
 294                         or \c NULL on error.
 295
 296 @prenotnull{stream_class}
 297 @postsuccessrefcountretinc
 298
 299 @sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
 300         context field type of a given stream class.
 301 */
 302 extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(
 303                 struct bt_ctf_stream_class *stream_class);
 304
 305 /**
 306 @brief  Sets the packet context field type of the CTF IR stream class
 307         \p stream_class to \p packet_context_type.
 308
 309 As of Babeltrace \btversion, \p packet_context_type \em must be a
 310 CTF IR structure field type object.
 311
 312 @param[in] stream_class         Stream class of which to set the packet
 313                                 context field type.
 314 @param[in] packet_context_type  Packet context field type.
 315 @returns                        0 on success, or a negative value on error.
 316
 317 @prenotnull{stream_class}
 318 @prenotnull{packet_context_type}
 319 @prehot{stream_class}
 320 @preisstructft{packet_context_type}
 321 @postrefcountsame{stream_class}
 322 @postsuccessrefcountinc{packet_context_type}
 323
 324 @sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
 325         context field type of a given stream class.
 326 */
 327 extern int bt_ctf_stream_class_set_packet_context_type(
 328                 struct bt_ctf_stream_class *stream_class,
 329                 struct bt_ctf_field_type *packet_context_type);
 330
 331 /**
 332 @brief  Returns the event header field type of the CTF IR stream class
 333         \p stream_class.
 334
 335 @param[in] stream_class Stream class of which to get the event header
 336                         field type.
 337 @returns                Event header field type of \p stream_class,
 338                         or \c NULL on error.
 339
 340 @prenotnull{stream_class}
 341 @postsuccessrefcountretinc
 342
 343 @sa bt_ctf_stream_class_set_event_header_type(): Sets the event
 344         header field type of a given stream class.
 345 */
 346 extern struct bt_ctf_field_type *
 347 bt_ctf_stream_class_get_event_header_type(
 348                 struct bt_ctf_stream_class *stream_class);
 349
 350 /**
 351 @brief  Sets the event header field type of the CTF IR stream class
 352         \p stream_class to \p event_header_type.
 353
 354 As of Babeltrace \btversion, \p event_header_type \em must be a
 355 CTF IR structure field type object.
 356
 357 @param[in] stream_class         Stream class of which to set the event
 358                                 header field type.
 359 @param[in] event_header_type    Event header field type.
 360 @returns                        0 on success, or a negative value on error.
 361
 362 @prenotnull{stream_class}
 363 @prenotnull{event_header_type}
 364 @prehot{stream_class}
 365 @preisstructft{event_header_type}
 366 @postrefcountsame{stream_class}
 367 @postsuccessrefcountinc{event_header_type}
 368
 369 @sa bt_ctf_stream_class_get_event_header_type(): Returns the event
 370         header field type of a given stream class.
 371 */
 372 extern int bt_ctf_stream_class_set_event_header_type(
 373                 struct bt_ctf_stream_class *stream_class,
 374                 struct bt_ctf_field_type *event_header_type);
 375
 376 /**
 377 @brief  Returns the per-stream class event context field type of the
 378         CTF IR stream class \p stream_class.
 379
 380 @param[in] stream_class Stream class of which to get the per-stream
 381                         class event context field type.
 382 @returns                Per-stream class event context field type of
 383                         \p stream_class, or \c NULL on error.
 384
 385 @prenotnull{stream_class}
 386 @postsuccessrefcountretinc
 387
 388 @sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
 389         class event context field type of a given stream class.
 390 */
 391 extern struct bt_ctf_field_type *
 392 bt_ctf_stream_class_get_event_context_type(
 393                 struct bt_ctf_stream_class *stream_class);
 394
 395 /**
 396 @brief  Sets the per-stream class event context field type of the CTF
 397         IR stream class \p stream_class to \p event_context_type.
 398
 399 As of Babeltrace \btversion, \p event_context_type \em must be a
 400 CTF IR structure field type object.
 401
 402 @param[in] stream_class         Stream class of which to set the
 403                                 per-stream class event context
 404                                 field type.
 405 @param[in] event_context_type   Per-stream class event context context
 406                                 field type.
 407 @returns                        0 on success, or a negative value on error.
 408
 409 @prenotnull{stream_class}
 410 @prenotnull{event_context_type}
 411 @prehot{stream_class}
 412 @preisstructft{event_context_type}
 413 @postrefcountsame{stream_class}
 414 @postsuccessrefcountinc{event_context_type}
 415
 416 @sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
 417         class event context field type of a given stream class.
 418 */
 419 extern int bt_ctf_stream_class_set_event_context_type(
 420                 struct bt_ctf_stream_class *stream_class,
 421                 struct bt_ctf_field_type *event_context_type);
 422
 423 /** @} */
 424
 425 /**
 426 @name Event class children functions
 427 @{
 428 */
 429
 430 /**
 431 @brief  Returns the number of event classes contained in the
 432         CTF IR stream class \p stream_class.
 433
 434 @param[in] stream_class Stream class of which to get the number
 435                         of children event classes.
 436 @returns                Number of children event classes
 437                         contained in \p stream_class, or
 438                         a negative value on error.
 439
 440 @prenotnull{stream_class}
 441 @postrefcountsame{stream_class}
 442 */
 443 extern int bt_ctf_stream_class_get_event_class_count(
 444                 struct bt_ctf_stream_class *stream_class);
 445
 446 /**
 447 @brief  Returns the event class at index \p index in the CTF IR stream
 448         class \p stream_class.
 449
 450 @param[in] stream_class Stream class of which to get the event class.
 451 @param[in] index        Index of the event class to find.
 452 @returns                Event class at index \p index, or \c NULL
 453                         on error.
 454
 455 @prenotnull{stream_class}
 456 @pre \p index is lesser than the number of event classes contained in the
 457         stream class \p stream_class (see
 458         bt_ctf_stream_class_get_event_class_count()).
 459 @postrefcountsame{stream_class}
 460 @postsuccessrefcountretinc
 461
 462 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
 463         by ID.
 464 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
 465         by name.
 466 */
 467 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
 468                 struct bt_ctf_stream_class *stream_class, int index);
 469
 470 /**
 471 @brief  Returns the event class named \c name found in the CTF IR stream
 472         class \p stream_class.
 473
 474 @param[in] stream_class Stream class of which to get the event class.
 475 @param[in] name         Name of the event class to find.
 476 @returns                Event class named \p name, or \c NULL
 477                         on error.
 478
 479 @prenotnull{stream_class}
 480 @prenotnull{name}
 481 @postrefcountsame{stream_class}
 482 @postsuccessrefcountretinc
 483
 484 @sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
 485         by ID.
 486 */
 487 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
 488                 struct bt_ctf_stream_class *stream_class, const char *name);
 489
 490 /**
 491 @brief  Returns the event class with ID \c id found in the CTF IR stream
 492         class \p stream_class.
 493
 494 @param[in] stream_class Stream class of which to get the event class.
 495 @param[in] id           ID of the event class to find.
 496 @returns                Event class with ID \p id, or \c NULL
 497                         on error.
 498
 499 @prenotnull{stream_class}
 500 @postrefcountsame{stream_class}
 501 @postsuccessrefcountretinc
 502
 503 @sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
 504         by name.
 505 */
 506 extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
 507                 struct bt_ctf_stream_class *stream_class, uint32_t id);
 508
 509 /**
 510 @brief  Adds the CTF IR event class \p event_class to the
 511         CTF IR stream class \p stream_class.
 512
 513 On success, \p event_class becomes the child of \p stream_class.
 514
 515 You can only add a given event class to one stream class.
 516
 517 You can call this function even if \p stream_class is frozen. Adding
 518 event classes is the only operation that is permitted
 519 on a frozen stream class.
 520
 521 @param[in] stream_class Stream class to which to add \p event_class.
 522 @param[in] event_class  Event class to add to \p stream_class.
 523 @returns                0 on success, or a negative value on error.
 524
 525 @prenotnull{stream_class}
 526 @prenotnull{event_class}
 527 @prehot{event_class}
 528 @postrefcountsame{stream_class}
 529 @postsuccessrefcountinc{event_class}
 530 @postsuccessfrozen{event_class}
 531 */
 532 extern int bt_ctf_stream_class_add_event_class(
 533                 struct bt_ctf_stream_class *stream_class,
 534                 struct bt_ctf_event_class *event_class);
 535
 536 /** @} */
 537
 538 /**
 539 @name Misc. function
 540 @{
 541 */
 542
 543 /**
 544 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 545         CTF IR stream class \p stream_class.
 546
 547 This function traverses the hierarchy of \p stream_class in pre-order
 548 and calls \p visitor on each element.
 549
 550 The stream class itself is visited first, and then all its children
 551 event classes.
 552
 553 @param[in] stream_class Stream class to visit.
 554 @param[in] visitor      Visiting function.
 555 @param[in] data         User data.
 556 @returns                0 on success, or a negative value on error.
 557
 558 @prenotnull{stream_class}
 559 @prenotnull{visitor}
 560 */
 561 extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class,
 562                 bt_ctf_visitor visitor, void *data);
 563
 564 /** @} */
 565
 566 /** @} */
 567
 568 // TODO: document for writer
 569 extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
 570                 struct bt_ctf_stream_class *stream_class);
 571
 572 #ifdef __cplusplus
 573 }
 574 #endif
 575
 576 #endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */