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