bindings/python/writer.py

   1 # writer.py
   2 #
   3 # Babeltrace writer interface Python module
   4 #
   5 # Copyright 2012-2015 EfficiOS Inc.
   6 #
   7 # Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8 #
   9 # Permission is hereby granted, free of charge, to any person obtaining a copy
  10 # of this software and associated documentation files (the "Software"), to deal
  11 # in the Software without restriction, including without limitation the rights
  12 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  13 # copies of the Software, and to permit persons to whom the Software is
  14 # furnished to do so, subject to the following conditions:
  15 #
  16 # The above copyright notice and this permission notice shall be included in
  17 # all copies or substantial portions of the Software.
  18 #
  19 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25 # SOFTWARE.
  26
  27 import babeltrace.nativebt as nbt
  28 import babeltrace.common as common
  29 from uuid import UUID
  30
  31
  32 # Used to compare to -1ULL in error checks
  33 _MAX_UINT64 = 0xFFFFFFFFFFFFFFFF
  34
  35
  36 class EnumerationMapping:
  37     """
  38     Mapping from an enumeration label to a range of integers.
  39     """
  40
  41     def __init__(self, name, start, end):
  42         """
  43         Creates an enumeration mapping, where label *name* is mapped to
  44         the [*start*, *end*] range of integers (*end* is included).
  45
  46         Set *start* and *end* to the same value to create an enumeration
  47         mapping to a single value.
  48         """
  49
  50         self.name = name
  51         self.start = start
  52         self.end = end
  53
  54
  55 class Clock:
  56     """
  57     A CTF clock allows the description of the system's clock topology, as
  58     well as the definition of each clock's parameters.
  59
  60     :class:`Clock` objects must be registered to a :class:`Writer`
  61     object (see :meth:`Writer.add_clock`), as well as be registered to
  62     a :class:`StreamClass` object (see :attr:`StreamClass.clock`).
  63     """
  64
  65     def __init__(self, name):
  66         """
  67         Creates a default CTF clock named *name*.
  68
  69         :exc:`ValueError` is raised on error.
  70         """
  71
  72         self._c = nbt._bt_ctf_clock_create(name)
  73
  74         if self._c is None:
  75             raise ValueError("Invalid clock name.")
  76
  77     def __del__(self):
  78         nbt._bt_ctf_clock_put(self._c)
  79
  80     @property
  81     def name(self):
  82         """
  83         Clock name.
  84
  85         Set this attribute to change the clock's name.
  86
  87         :exc:`ValueError` is raised on error.
  88         """
  89
  90         name = nbt._bt_ctf_clock_get_name(self._c)
  91
  92         if name is None:
  93             raise ValueError("Invalid clock instance.")
  94
  95         return name
  96
  97     @property
  98     def description(self):
  99         """
 100         Clock description (string).
 101
 102         Set this attribute to change the clock's description.
 103
 104         :exc:`ValueError` is raised on error.
 105         """
 106
 107         return nbt._bt_ctf_clock_get_description(self._c)
 108
 109     @description.setter
 110     def description(self, desc):
 111         ret = nbt._bt_ctf_clock_set_description(self._c, str(desc))
 112
 113         if ret < 0:
 114             raise ValueError("Invalid clock description.")
 115
 116     @property
 117     def frequency(self):
 118         """
 119         Clock frequency in Hz (integer).
 120
 121         Set this attribute to change the clock's frequency.
 122
 123         :exc:`ValueError` is raised on error.
 124         """
 125
 126         freq = nbt._bt_ctf_clock_get_frequency(self._c)
 127
 128         if freq == _MAX_UINT64:
 129             raise ValueError("Invalid clock instance")
 130
 131         return freq
 132
 133     @frequency.setter
 134     def frequency(self, freq):
 135         ret = nbt._bt_ctf_clock_set_frequency(self._c, freq)
 136
 137         if ret < 0:
 138             raise ValueError("Invalid frequency value.")
 139
 140     @property
 141     def precision(self):
 142         """
 143         Clock precision in clock ticks (integer).
 144
 145         Set this attribute to change the clock's precision.
 146
 147         :exc:`ValueError` is raised on error.
 148         """
 149
 150         precision = nbt._bt_ctf_clock_get_precision(self._c)
 151
 152         if precision == _MAX_UINT64:
 153             raise ValueError("Invalid clock instance")
 154
 155         return precision
 156
 157     @precision.setter
 158     def precision(self, precision):
 159         ret = nbt._bt_ctf_clock_set_precision(self._c, precision)
 160
 161     @property
 162     def offset_seconds(self):
 163         """
 164         Clock offset in seconds since POSIX.1 Epoch (integer).
 165
 166         Set this attribute to change the clock's offset in seconds.
 167
 168         :exc:`ValueError` is raised on error.
 169         """
 170
 171         offset_s = nbt._bt_ctf_clock_get_offset_s(self._c)
 172
 173         if offset_s == _MAX_UINT64:
 174             raise ValueError("Invalid clock instance")
 175
 176         return offset_s
 177
 178     @offset_seconds.setter
 179     def offset_seconds(self, offset_s):
 180         ret = nbt._bt_ctf_clock_set_offset_s(self._c, offset_s)
 181
 182         if ret < 0:
 183             raise ValueError("Invalid offset value.")
 184
 185     @property
 186     def offset(self):
 187         """
 188         Clock offset in ticks since (POSIX.1 Epoch +
 189         :attr:`offset_seconds`).
 190
 191         Set this attribute to change the clock's offset.
 192
 193         :exc:`ValueError` is raised on error.
 194         """
 195
 196         offset = nbt._bt_ctf_clock_get_offset(self._c)
 197
 198         if offset == _MAX_UINT64:
 199             raise ValueError("Invalid clock instance")
 200
 201         return offset
 202
 203     @offset.setter
 204     def offset(self, offset):
 205         ret = nbt._bt_ctf_clock_set_offset(self._c, offset)
 206
 207         if ret < 0:
 208             raise ValueError("Invalid offset value.")
 209
 210     @property
 211     def absolute(self):
 212         """
 213         ``True`` if this clock is absolute, i.e. if the clock is a
 214         global reference across the other clocks of the trace.
 215
 216         Set this attribute to change the clock's absolute state
 217         (boolean).
 218
 219         :exc:`ValueError` is raised on error.
 220         """
 221
 222         is_absolute = nbt._bt_ctf_clock_get_is_absolute(self._c)
 223
 224         if is_absolute == -1:
 225             raise ValueError("Invalid clock instance")
 226
 227         return False if is_absolute == 0 else True
 228
 229     @absolute.setter
 230     def absolute(self, is_absolute):
 231         ret = nbt._bt_ctf_clock_set_is_absolute(self._c, int(is_absolute))
 232
 233         if ret < 0:
 234             raise ValueError("Could not set the clock absolute attribute.")
 235
 236     @property
 237     def uuid(self):
 238         """
 239         Clock UUID (an :class:`uuid.UUID` object).
 240
 241         Set this attribute to change the clock's UUID.
 242
 243         :exc:`ValueError` is raised on error.
 244         """
 245
 246         uuid_list = []
 247
 248         for i in range(16):
 249             ret, value = nbt._bt_python_ctf_clock_get_uuid_index(self._c, i)
 250
 251             if ret < 0:
 252                 raise ValueError("Invalid clock instance")
 253
 254             uuid_list.append(value)
 255
 256         return UUID(bytes=bytes(uuid_list))
 257
 258     @uuid.setter
 259     def uuid(self, uuid):
 260         uuid_bytes = uuid.bytes
 261
 262         if len(uuid_bytes) != 16:
 263             raise ValueError("Invalid UUID provided. UUID length must be 16 bytes")
 264
 265         for i in range(len(uuid_bytes)):
 266             ret = nbt._bt_python_ctf_clock_set_uuid_index(self._c, i,
 267                                                           uuid_bytes[i])
 268
 269             if ret < 0:
 270                 raise ValueError("Invalid clock instance")
 271
 272     @property
 273     def time(self):
 274         """
 275         Clock current time; nanoseconds (integer) since clock origin
 276         (POSIX.1 Epoch + :attr:`offset_seconds` + :attr:`offset`).
 277
 278         Set this attribute to change the clock's current time.
 279
 280         :exc:`ValueError` is raised on error.
 281         """
 282
 283         time = nbt._bt_ctf_clock_get_time(self._c)
 284
 285         if time == _MAX_UINT64:
 286             raise ValueError("Invalid clock instance")
 287
 288         return time
 289
 290     @time.setter
 291     def time(self, time):
 292         ret = nbt._bt_ctf_clock_set_time(self._c, time)
 293
 294         if ret < 0:
 295             raise ValueError("Invalid time value.")
 296
 297
 298 class IntegerBase:
 299     """
 300     Display base of an integer.
 301     """
 302
 303     #: Unknown
 304     INTEGER_BASE_UNKNOWN = -1
 305
 306     #: Binary
 307     INTEGER_BASE_BINARY = 2
 308
 309     #: Octal
 310     INTEGER_BASE_OCTAL = 8
 311
 312     #: Decimal
 313     INTEGER_BASE_DECIMAL = 10
 314
 315     #: Hexadecimal
 316     INTEGER_BASE_HEXADECIMAL = 16
 317
 318
 319 class FieldDeclaration:
 320     """
 321     Base class of all field declarations. This class is not meant to
 322     be instantiated by the user; use one of the concrete field
 323     declaration subclasses instead.
 324     """
 325
 326     class IntegerBase(IntegerBase):
 327         pass
 328
 329     def __init__(self):
 330         if self._ft is None:
 331             raise ValueError("FieldDeclaration creation failed.")
 332
 333     def __del__(self):
 334         nbt._bt_ctf_field_type_put(self._ft)
 335
 336     @staticmethod
 337     def _create_field_declaration_from_native_instance(
 338             native_field_declaration):
 339         type_dict = {
 340             common.CTFTypeId.INTEGER: IntegerFieldDeclaration,
 341             common.CTFTypeId.FLOAT: FloatFieldDeclaration,
 342             common.CTFTypeId.ENUM: EnumerationFieldDeclaration,
 343             common.CTFTypeId.STRING: StringFieldDeclaration,
 344             common.CTFTypeId.STRUCT: StructureFieldDeclaration,
 345             common.CTFTypeId.VARIANT: VariantFieldDeclaration,
 346             common.CTFTypeId.ARRAY: ArrayFieldDeclaration,
 347             common.CTFTypeId.SEQUENCE: SequenceFieldDeclaration
 348         }
 349
 350         field_type_id = nbt._bt_ctf_field_type_get_type_id(native_field_declaration)
 351
 352         if field_type_id == common.CTFTypeId.UNKNOWN:
 353             raise TypeError("Invalid field instance")
 354
 355         declaration = Field.__new__(Field)
 356         declaration._ft = native_field_declaration
 357         declaration.__class__ = type_dict[field_type_id]
 358
 359         return declaration
 360
 361     @property
 362     def alignment(self):
 363         """
 364         Field alignment in bits (integer).
 365
 366         Set this attribute to change this field's alignment.
 367
 368         :exc:`ValueError` is raised on error.
 369         """
 370
 371         return nbt._bt_ctf_field_type_get_alignment(self._ft)
 372
 373     @alignment.setter
 374     def alignment(self, alignment):
 375         ret = nbt._bt_ctf_field_type_set_alignment(self._ft, alignment)
 376
 377         if ret < 0:
 378             raise ValueError("Invalid alignment value.")
 379
 380     @property
 381     def byte_order(self):
 382         """
 383         Field byte order (one of :class:`babeltrace.common.ByteOrder`
 384         constants).
 385
 386         Set this attribute to change this field's byte order.
 387
 388         :exc:`ValueError` is raised on error.
 389         """
 390
 391         return nbt._bt_ctf_field_type_get_byte_order(self._ft)
 392
 393     @byte_order.setter
 394     def byte_order(self, byte_order):
 395         ret = nbt._bt_ctf_field_type_set_byte_order(self._ft, byte_order)
 396
 397         if ret < 0:
 398             raise ValueError("Could not set byte order value.")
 399
 400
 401 class IntegerFieldDeclaration(FieldDeclaration):
 402     """
 403     Integer field declaration.
 404     """
 405
 406     def __init__(self, size):
 407         """
 408         Creates an integer field declaration of size *size* bits.
 409
 410         :exc:`ValueError` is raised on error.
 411         """
 412
 413         self._ft = nbt._bt_ctf_field_type_integer_create(size)
 414         super().__init__()
 415
 416     @property
 417     def size(self):
 418         """
 419         Integer size in bits (integer).
 420
 421         Set this attribute to change this integer's size.
 422
 423         :exc:`ValueError` is raised on error.
 424         """
 425
 426         ret = nbt._bt_ctf_field_type_integer_get_size(self._ft)
 427
 428         if ret < 0:
 429             raise ValueError("Could not get Integer size attribute.")
 430         else:
 431             return ret
 432
 433     @property
 434     def signed(self):
 435         """
 436         ``True`` if this integer is signed.
 437
 438         Set this attribute to change this integer's signedness
 439         (boolean).
 440
 441         :exc:`ValueError` is raised on error.
 442         """
 443
 444         ret = nbt._bt_ctf_field_type_integer_get_signed(self._ft)
 445
 446         if ret < 0:
 447             raise ValueError("Could not get Integer signed attribute.")
 448         elif ret > 0:
 449             return True
 450         else:
 451             return False
 452
 453     @signed.setter
 454     def signed(self, signed):
 455         ret = nbt._bt_ctf_field_type_integer_set_signed(self._ft, signed)
 456
 457         if ret < 0:
 458             raise ValueError("Could not set Integer signed attribute.")
 459
 460     @property
 461     def base(self):
 462         """
 463         Integer display base (one of :class:`IntegerBase` constants).
 464
 465         Set this attribute to change this integer's display base.
 466
 467         :exc:`ValueError` is raised on error.
 468         """
 469
 470         return nbt._bt_ctf_field_type_integer_get_base(self._ft)
 471
 472     @base.setter
 473     def base(self, base):
 474         ret = nbt._bt_ctf_field_type_integer_set_base(self._ft, base)
 475
 476         if ret < 0:
 477             raise ValueError("Could not set Integer base.")
 478
 479     @property
 480     def encoding(self):
 481         """
 482         Integer encoding (one of
 483         :class:`babeltrace.common.CTFStringEncoding` constants).
 484
 485         Set this attribute to change this integer's encoding.
 486
 487         :exc:`ValueError` is raised on error.
 488         """
 489
 490         return nbt._bt_ctf_field_type_integer_get_encoding(self._ft)
 491
 492     @encoding.setter
 493     def encoding(self, encoding):
 494         ret = nbt._bt_ctf_field_type_integer_set_encoding(self._ft, encoding)
 495
 496         if ret < 0:
 497             raise ValueError("Could not set Integer encoding.")
 498
 499
 500 class EnumerationFieldDeclaration(FieldDeclaration):
 501     """
 502     Enumeration field declaration. A CTF enumeration maps labels to
 503     ranges of integers.
 504     """
 505
 506     def __init__(self, integer_type):
 507         """
 508         Creates an enumeration field declaration, with *integer_type*
 509         being the underlying :class:`IntegerFieldDeclaration` for storing
 510         the integer.
 511
 512         :exc:`ValueError` is raised on error.
 513         """
 514
 515         isinst = isinstance(integer_type, IntegerFieldDeclaration)
 516
 517         if integer_type is None or not isinst:
 518             raise TypeError("Invalid integer container.")
 519
 520         self._ft = nbt._bt_ctf_field_type_enumeration_create(integer_type._ft)
 521         super().__init__()
 522
 523     @property
 524     def container(self):
 525         """
 526         Underlying container (:class:`IntegerFieldDeclaration`).
 527
 528         :exc:`TypeError` is raised on error.
 529         """
 530
 531         ret = nbt._bt_ctf_field_type_enumeration_get_container_type(self._ft)
 532
 533         if ret is None:
 534             raise TypeError("Invalid enumeration declaration")
 535
 536         return FieldDeclaration._create_field_declaration_from_native_instance(ret)
 537
 538     def add_mapping(self, name, range_start, range_end):
 539         """
 540         Adds a mapping to the enumeration field declaration, from the
 541         label named *name* to range [*range_start*, *range_end*], where
 542         *range_start* and *range_end* are integers included in the
 543         range.
 544
 545         :exc:`ValueError` is raised on error.
 546         """
 547
 548         if range_start < 0 or range_end < 0:
 549             ret = nbt._bt_ctf_field_type_enumeration_add_mapping(self._ft,
 550                                                                  str(name),
 551                                                                  range_start,
 552                                                                  range_end)
 553         else:
 554             ret = nbt._bt_ctf_field_type_enumeration_add_mapping_unsigned(self._ft,
 555                                                                           str(name),
 556                                                                           range_start,
 557                                                                           range_end)
 558
 559         if ret < 0:
 560             raise ValueError("Could not add mapping to enumeration declaration.")
 561
 562     @property
 563     def mappings(self):
 564         """
 565         Generates the mappings of this enumeration field declaration
 566         (:class:`EnumerationMapping` objects).
 567
 568         :exc:`TypeError` is raised on error.
 569         """
 570
 571         signed = self.container.signed
 572
 573         count = nbt._bt_ctf_field_type_enumeration_get_mapping_count(self._ft)
 574
 575         for i in range(count):
 576             if signed:
 577                 ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping(self._ft, i)
 578             else:
 579                 ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping_unsigned(self._ft, i)
 580
 581             if len(ret) != 3:
 582                 msg = "Could not get Enumeration mapping at index {}".format(i)
 583                 raise TypeError(msg)
 584
 585             name, range_start, range_end = ret
 586             yield EnumerationMapping(name, range_start, range_end)
 587
 588     def get_mapping_by_name(self, name):
 589         """
 590         Returns the :class:`EnumerationMapping` object for the label
 591         named *name*.
 592
 593         :exc:`TypeError` is raised on error.
 594         """
 595
 596         index = nbt._bt_ctf_field_type_enumeration_get_mapping_index_by_name(self._ft, name)
 597
 598         if index < 0:
 599             return None
 600
 601         if self.container.signed:
 602             ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping(self._ft, index)
 603         else:
 604             ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping_unsigned(self._ft, index)
 605
 606         if len(ret) != 3:
 607             msg = "Could not get Enumeration mapping at index {}".format(i)
 608             raise TypeError(msg)
 609
 610         name, range_start, range_end = ret
 611
 612         return EnumerationMapping(name, range_start, range_end)
 613
 614     def get_mapping_by_value(self, value):
 615         """
 616         Returns the :class:`EnumerationMapping` object for the value
 617         *value* (integer).
 618
 619         :exc:`TypeError` is raised on error.
 620         """
 621
 622         if value < 0:
 623             index = nbt._bt_ctf_field_type_enumeration_get_mapping_index_by_value(self._ft, value)
 624         else:
 625             index = nbt._bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(self._ft, value)
 626
 627         if index < 0:
 628             return None
 629
 630         if self.container.signed:
 631             ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping(self._ft, index)
 632         else:
 633             ret = nbt._bt_python_ctf_field_type_enumeration_get_mapping_unsigned(self._ft, index)
 634
 635         if len(ret) != 3:
 636             msg = "Could not get Enumeration mapping at index {}".format(i)
 637             raise TypeError(msg)
 638
 639         name, range_start, range_end = ret
 640
 641         return EnumerationMapping(name, range_start, range_end)
 642
 643
 644 class FloatingPointFieldDeclaration(FieldDeclaration):
 645     """
 646     Floating point number field declaration.
 647
 648     A CTF floating point number is a made of three sections: the sign
 649     bit, the exponent bits, and the mantissa bits. The most significant
 650     bit of the resulting binary word is the sign bit, and is included
 651     in the number of mantissa bits.
 652
 653     For example, the
 654     `IEEE 754 <http://en.wikipedia.org/wiki/IEEE_floating_point>`_
 655     single precision floating point number is represented on a 32-bit
 656     word using an 8-bit exponent (``e``) and a 24-bit mantissa (``m``),
 657     the latter count including the sign bit (``s``)::
 658
 659         s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
 660
 661     The IEEE 754 double precision floating point number uses an
 662     11-bit exponent and a 53-bit mantissa.
 663     """
 664
 665     #: IEEE 754 single precision floating point number exponent size
 666     FLT_EXP_DIG = 8
 667
 668     #: IEEE 754 double precision floating point number exponent size
 669     DBL_EXP_DIG = 11
 670
 671     #: IEEE 754 single precision floating point number mantissa size
 672     FLT_MANT_DIG = 24
 673
 674     #: IEEE 754 double precision floating point number mantissa size
 675     DBL_MANT_DIG = 53
 676
 677     def __init__(self):
 678         """
 679         Creates a floating point number field declaration.
 680
 681         :exc:`ValueError` is raised on error.
 682         """
 683
 684         self._ft = nbt._bt_ctf_field_type_floating_point_create()
 685         super().__init__()
 686
 687     @property
 688     def exponent_digits(self):
 689         """
 690         Floating point number exponent section size in bits (integer).
 691
 692         Set this attribute to change the floating point number's
 693         exponent section's size. You may use :attr:`FLT_EXP_DIG` or
 694         :attr:`DBL_EXP_DIG` for IEEE 754 floating point numbers.
 695
 696         :exc:`ValueError` is raised on error.
 697         """
 698
 699         ret = nbt._bt_ctf_field_type_floating_point_get_exponent_digits(self._ft)
 700
 701         if ret < 0:
 702             raise TypeError(
 703                 "Could not get Floating point exponent digit count")
 704
 705         return ret
 706
 707     @exponent_digits.setter
 708     def exponent_digits(self, exponent_digits):
 709         ret = nbt._bt_ctf_field_type_floating_point_set_exponent_digits(self._ft,
 710                                                                         exponent_digits)
 711
 712         if ret < 0:
 713             raise ValueError("Could not set exponent digit count.")
 714
 715     @property
 716     def mantissa_digits(self):
 717         """
 718         Floating point number mantissa section size in bits (integer).
 719
 720         Set this attribute to change the floating point number's
 721         mantissa section's size. You may use :attr:`FLT_MANT_DIG` or
 722         :attr:`DBL_MANT_DIG` for IEEE 754 floating point numbers.
 723
 724         :exc:`ValueError` is raised on error.
 725         """
 726
 727         ret = nbt._bt_ctf_field_type_floating_point_get_mantissa_digits(self._ft)
 728
 729         if ret < 0:
 730             raise TypeError("Could not get Floating point mantissa digit count")
 731
 732         return ret
 733
 734     @mantissa_digits.setter
 735     def mantissa_digits(self, mantissa_digits):
 736         ret = nbt._bt_ctf_field_type_floating_point_set_mantissa_digits(self._ft,
 737                                                                         mantissa_digits)
 738
 739         if ret < 0:
 740             raise ValueError("Could not set mantissa digit count.")
 741
 742
 743 class FloatFieldDeclaration(FloatingPointFieldDeclaration):
 744     pass
 745
 746
 747 class StructureFieldDeclaration(FieldDeclaration):
 748     """
 749     Structure field declaration, i.e. an ordered mapping from field
 750     names to field declarations.
 751     """
 752
 753     def __init__(self):
 754         """
 755         Creates an empty structure field declaration.
 756
 757         :exc:`ValueError` is raised on error.
 758         """
 759
 760         self._ft = nbt._bt_ctf_field_type_structure_create()
 761         super().__init__()
 762
 763     def add_field(self, field_type, field_name):
 764         """
 765         Appends one :class:`FieldDeclaration` *field_type* named
 766         *field_name* to the structure's ordered map.
 767
 768         :exc:`ValueError` is raised on error.
 769         """
 770
 771         ret = nbt._bt_ctf_field_type_structure_add_field(self._ft,
 772                                                          field_type._ft,
 773                                                          str(field_name))
 774
 775         if ret < 0:
 776             raise ValueError("Could not add field to structure.")
 777
 778     @property
 779     def fields(self):
 780         """
 781         Generates the (field name, :class:`FieldDeclaration`) pairs
 782         of this structure.
 783
 784         :exc:`TypeError` is raised on error.
 785         """
 786
 787         count = nbt._bt_ctf_field_type_structure_get_field_count(self._ft)
 788
 789         if count < 0:
 790             raise TypeError("Could not get Structure field count")
 791
 792         for i in range(count):
 793             field_name = nbt._bt_python_ctf_field_type_structure_get_field_name(self._ft, i)
 794
 795             if field_name is None:
 796                 msg = "Could not get Structure field name at index {}".format(i)
 797                 raise TypeError(msg)
 798
 799             field_type_native = nbt._bt_python_ctf_field_type_structure_get_field_type(self._ft, i)
 800
 801             if field_type_native is None:
 802                 msg = "Could not get Structure field type at index {}".format(i)
 803                 raise TypeError(msg)
 804
 805             field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
 806             yield (field_name, field_type)
 807
 808     def get_field_by_name(self, name):
 809         """
 810         Returns the :class:`FieldDeclaration` mapped to the field name
 811         *name* in this structure.
 812
 813         :exc:`TypeError` is raised on error.
 814         """
 815
 816         field_type_native = nbt._bt_ctf_field_type_structure_get_field_type_by_name(self._ft, name)
 817
 818         if field_type_native is None:
 819             msg = "Could not find Structure field with name {}".format(name)
 820             raise TypeError(msg)
 821
 822         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
 823
 824
 825 class VariantFieldDeclaration(FieldDeclaration):
 826     """
 827     Variant field declaration.
 828
 829     A CTF variant is a dynamic selection between different fields.
 830     The value of a *tag* (a CTF enumeration) determines what is the
 831     current selected field. All the possible fields must be added to
 832     its field declaration before using an actual variant field.
 833     """
 834
 835     def __init__(self, enum_tag, tag_name):
 836         """
 837         Creates an empty variant field declaration with tag field
 838         declaration *enum_tag* (instance of
 839         :class:`EnumerationFieldDeclaration`) named *tag_name*
 840         (string).
 841
 842         :exc:`ValueError` is raised on error.
 843         """
 844
 845         isinst = isinstance(enum_tag, EnumerationFieldDeclaration)
 846         if enum_tag is None or not isinst:
 847             raise TypeError("Invalid tag type; must be of type EnumerationFieldDeclaration.")
 848
 849         self._ft = nbt._bt_ctf_field_type_variant_create(enum_tag._ft,
 850                                                          str(tag_name))
 851         super().__init__()
 852
 853     @property
 854     def tag_name(self):
 855         """
 856         Variant field declaration tag name.
 857
 858         :exc:`TypeError` is raised on error.
 859         """
 860
 861         ret = nbt._bt_ctf_field_type_variant_get_tag_name(self._ft)
 862
 863         if ret is None:
 864             raise TypeError("Could not get Variant tag name")
 865
 866         return ret
 867
 868     @property
 869     def tag_type(self):
 870         """
 871         Variant field declaration tag field declaration
 872         (:class:`EnumerationFieldDeclaration` object).
 873
 874         :exc:`TypeError` is raised on error.
 875         """
 876
 877         ret = nbt._bt_ctf_field_type_variant_get_tag_type(self._ft)
 878
 879         if ret is None:
 880             raise TypeError("Could not get Variant tag type")
 881
 882         return FieldDeclaration._create_field_declaration_from_native_instance(ret)
 883
 884     def add_field(self, field_type, field_name):
 885         """
 886         Registers the :class:`FieldDeclaration` object *field_type*
 887         as the variant's selected type when the variant's tag's current
 888         label is *field_name*.
 889
 890         :exc:`ValueError` is raised on error.
 891         """
 892
 893         ret = nbt._bt_ctf_field_type_variant_add_field(self._ft,
 894                                                        field_type._ft,
 895                                                        str(field_name))
 896
 897         if ret < 0:
 898             raise ValueError("Could not add field to variant.")
 899
 900     @property
 901     def fields(self):
 902         """
 903         Generates the (field name, :class:`FieldDeclaration`) pairs
 904         of this variant field declaration.
 905
 906         :exc:`TypeError` is raised on error.
 907         """
 908
 909         count = nbt._bt_ctf_field_type_variant_get_field_count(self._ft)
 910
 911         if count < 0:
 912             raise TypeError("Could not get Variant field count")
 913
 914         for i in range(count):
 915             field_name = nbt._bt_python_ctf_field_type_variant_get_field_name(self._ft, i)
 916
 917             if field_name is None:
 918                 msg = "Could not get Variant field name at index {}".format(i)
 919                 raise TypeError(msg)
 920
 921             field_type_native = nbt._bt_python_ctf_field_type_variant_get_field_type(self._ft, i)
 922
 923             if field_type_native is None:
 924                 msg = "Could not get Variant field type at index {}".format(i)
 925                 raise TypeError(msg)
 926
 927             field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
 928             yield (field_name, field_type)
 929
 930     def get_field_by_name(self, name):
 931         """
 932         Returns the :class:`FieldDeclaration` selected when the
 933         variant's tag's current label is *name*.
 934
 935         :exc:`TypeError` is raised on error.
 936         """
 937
 938         field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_by_name(self._ft,
 939                                                                                   name)
 940
 941         if field_type_native is None:
 942             msg = "Could not find Variant field with name {}".format(name)
 943             raise TypeError(msg)
 944
 945         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
 946
 947     def get_field_from_tag(self, tag):
 948         """
 949         Returns the :class:`FieldDeclaration` selected by the current
 950         label of the :class:`EnumerationField` *tag*.
 951
 952         :exc:`TypeError` is raised on error.
 953         """
 954
 955         field_type_native = nbt._bt_ctf_field_type_variant_get_field_type_from_tag(self._ft, tag._f)
 956
 957         if field_type_native is None:
 958             msg = "Could not find Variant field with tag value {}".format(tag.value)
 959             raise TypeError(msg)
 960
 961         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
 962
 963
 964 class ArrayFieldDeclaration(FieldDeclaration):
 965     """
 966     Static array field declaration.
 967     """
 968
 969     def __init__(self, element_type, length):
 970         """
 971         Creates a static array field declaration of *length*
 972         elements of type *element_type* (:class:`FieldDeclaration`).
 973
 974         :exc:`ValueError` is raised on error.
 975         """
 976
 977         self._ft = nbt._bt_ctf_field_type_array_create(element_type._ft,
 978                                                        length)
 979         super().__init__()
 980
 981     @property
 982     def element_type(self):
 983         """
 984         Type of the elements of this this static array (subclass of
 985         :class:`FieldDeclaration`).
 986
 987         :exc:`TypeError` is raised on error.
 988         """
 989
 990         ret = nbt._bt_ctf_field_type_array_get_element_type(self._ft)
 991
 992         if ret is None:
 993             raise TypeError("Could not get Array element type")
 994
 995         return FieldDeclaration._create_field_declaration_from_native_instance(ret)
 996
 997     @property
 998     def length(self):
 999         """
1000         Length of this static array (integer).
1001
1002         :exc:`TypeError` is raised on error.
1003         """
1004
1005         ret = nbt._bt_ctf_field_type_array_get_length(self._ft)
1006
1007         if ret < 0:
1008             raise TypeError("Could not get Array length")
1009
1010         return ret
1011
1012
1013 class SequenceFieldDeclaration(FieldDeclaration):
1014     """
1015     Sequence (dynamic array) field declaration.
1016     """
1017
1018     def __init__(self, element_type, length_field_name):
1019         """
1020         Creates a sequence field declaration of
1021         elements of type *element_type* (:class:`FieldDeclaration`).
1022         The length of a sequence field based on this sequence field
1023         declaration is obtained by retrieving the dynamic integer
1024         value of the field named *length_field_name*.
1025
1026         :exc:`ValueError` is raised on error.
1027         """
1028
1029         self._ft = nbt._bt_ctf_field_type_sequence_create(element_type._ft,
1030                                                           str(length_field_name))
1031         super().__init__()
1032
1033     @property
1034     def element_type(self):
1035         """
1036         Type of the elements of this sequence (subclass of
1037         :class:`FieldDeclaration`).
1038
1039         :exc:`TypeError` is raised on error.
1040         """
1041
1042         ret = nbt._bt_ctf_field_type_sequence_get_element_type(self._ft)
1043
1044         if ret is None:
1045             raise TypeError("Could not get Sequence element type")
1046
1047         return FieldDeclaration._create_field_declaration_from_native_instance(ret)
1048
1049     @property
1050     def length_field_name(self):
1051         """
1052         Name of the integer field defining the dynamic length of
1053         sequence fields based on this sequence field declaration.
1054
1055         :exc:`TypeError` is raised on error.
1056         """
1057
1058         ret = nbt._bt_ctf_field_type_sequence_get_length_field_name(self._ft)
1059
1060         if ret is None:
1061             raise TypeError("Could not get Sequence length field name")
1062
1063         return ret
1064
1065
1066 class StringFieldDeclaration(FieldDeclaration):
1067     """
1068     String (NULL-terminated array of bytes) field declaration.
1069     """
1070
1071     def __init__(self):
1072         """
1073         Creates a string field declaration.
1074
1075         :exc:`ValueError` is raised on error.
1076         """
1077
1078         self._ft = nbt._bt_ctf_field_type_string_create()
1079         super().__init__()
1080
1081     @property
1082     def encoding(self):
1083         """
1084         String encoding (one of
1085         :class:`babeltrace.common.CTFStringEncoding` constants).
1086
1087         Set this attribute to change this string's encoding.
1088
1089         :exc:`ValueError` is raised on error.
1090         """
1091
1092         return nbt._bt_ctf_field_type_string_get_encoding(self._ft)
1093
1094     @encoding.setter
1095     def encoding(self, encoding):
1096         ret = nbt._bt_ctf_field_type_string_set_encoding(self._ft, encoding)
1097         if ret < 0:
1098             raise ValueError("Could not set string encoding.")
1099
1100
1101 @staticmethod
1102 def create_field(field_type):
1103     """
1104     Create an instance of a field.
1105     """
1106     isinst = isinstance(field_type, FieldDeclaration)
1107
1108     if field_type is None or not isinst:
1109         raise TypeError("Invalid field_type. Type must be a FieldDeclaration-derived class.")
1110
1111     if isinstance(field_type, IntegerFieldDeclaration):
1112         return IntegerField(field_type)
1113     elif isinstance(field_type, EnumerationFieldDeclaration):
1114         return EnumerationField(field_type)
1115     elif isinstance(field_type, FloatFieldDeclaration):
1116         return FloatingPointField(field_type)
1117     elif isinstance(field_type, StructureFieldDeclaration):
1118         return StructureField(field_type)
1119     elif isinstance(field_type, VariantFieldDeclaration):
1120         return VariantField(field_type)
1121     elif isinstance(field_type, ArrayFieldDeclaration):
1122         return ArrayField(field_type)
1123     elif isinstance(field_type, SequenceFieldDeclaration):
1124         return SequenceField(field_type)
1125     elif isinstance(field_type, StringFieldDeclaration):
1126         return StringField(field_type)
1127
1128
1129 class Field:
1130     """
1131     Base class of all fields. This class is not meant to be
1132     instantiated by the user, and neither are its subclasses. Use
1133     :meth:`Event.payload` to access specific, concrete fields of
1134     an event.
1135     """
1136
1137     def __init__(self, field_type):
1138         if not isinstance(field_type, FieldDeclaration):
1139             raise TypeError("Invalid field_type argument.")
1140
1141         self._f = nbt._bt_ctf_field_create(field_type._ft)
1142
1143         if self._f is None:
1144             raise ValueError("Field creation failed.")
1145
1146     def __del__(self):
1147         nbt._bt_ctf_field_put(self._f)
1148
1149     @staticmethod
1150     def _create_field_from_native_instance(native_field_instance):
1151         type_dict = {
1152             common.CTFTypeId.INTEGER: IntegerField,
1153             common.CTFTypeId.FLOAT: FloatingPointField,
1154             common.CTFTypeId.ENUM: EnumerationField,
1155             common.CTFTypeId.STRING: StringField,
1156             common.CTFTypeId.STRUCT: StructureField,
1157             common.CTFTypeId.VARIANT: VariantField,
1158             common.CTFTypeId.ARRAY: ArrayField,
1159             common.CTFTypeId.SEQUENCE: SequenceField
1160         }
1161
1162         field_type = nbt._bt_python_get_field_type(native_field_instance)
1163
1164         if field_type == common.CTFTypeId.UNKNOWN:
1165             raise TypeError("Invalid field instance")
1166
1167         field = Field.__new__(Field)
1168         field._f = native_field_instance
1169         field.__class__ = type_dict[field_type]
1170
1171         return field
1172
1173     @property
1174     def declaration(self):
1175         """
1176         Field declaration (subclass of :class:`FieldDeclaration`).
1177
1178         :exc:`TypeError` is raised on error.
1179         """
1180
1181         native_field_type = nbt._bt_ctf_field_get_type(self._f)
1182
1183         if native_field_type is None:
1184             raise TypeError("Invalid field instance")
1185         return FieldDeclaration._create_field_declaration_from_native_instance(
1186             native_field_type)
1187
1188
1189 class IntegerField(Field):
1190     """
1191     Integer field, based on an :class:`IntegerFieldDeclaration` object.
1192     """
1193
1194     @property
1195     def value(self):
1196         """
1197         Integer value (:class:`int`).
1198
1199         Set this attribute to change the integer field's value.
1200
1201         :exc:`ValueError` or :exc:`TypeError` are raised on error.
1202         """
1203
1204         signedness = nbt._bt_python_field_integer_get_signedness(self._f)
1205
1206         if signedness < 0:
1207             raise TypeError("Invalid integer instance.")
1208
1209         if signedness == 0:
1210             ret, value = nbt._bt_ctf_field_unsigned_integer_get_value(self._f)
1211         else:
1212             ret, value = nbt._bt_ctf_field_signed_integer_get_value(self._f)
1213
1214         if ret < 0:
1215             raise ValueError("Could not get integer field value.")
1216
1217         return value
1218
1219     @value.setter
1220     def value(self, value):
1221         if not isinstance(value, int):
1222             raise TypeError("IntegerField's value must be an int")
1223
1224         signedness = nbt._bt_python_field_integer_get_signedness(self._f)
1225         if signedness < 0:
1226             raise TypeError("Invalid integer instance.")
1227
1228         if signedness == 0:
1229             ret = nbt._bt_ctf_field_unsigned_integer_set_value(self._f, value)
1230         else:
1231             ret = nbt._bt_ctf_field_signed_integer_set_value(self._f, value)
1232
1233         if ret < 0:
1234             raise ValueError("Could not set integer field value.")
1235
1236
1237 class EnumerationField(Field):
1238     """
1239     Enumeration field, based on an
1240     :class:`EnumerationFieldDeclaration` object.
1241     """
1242
1243     @property
1244     def container(self):
1245         """
1246         Underlying container (:class:`IntegerField`).
1247
1248         :exc:`TypeError` is raised on error.
1249         """
1250
1251         container = IntegerField.__new__(IntegerField)
1252         container._f = nbt._bt_ctf_field_enumeration_get_container(self._f)
1253
1254         if container._f is None:
1255             raise TypeError("Invalid enumeration field type.")
1256
1257         return container
1258
1259     @property
1260     def value(self):
1261         """
1262         Current label of this enumeration field (:class:`str`).
1263
1264         Set this attribute to an integer (:class:`int`) to change the
1265         enumeration field's value.
1266
1267         :exc:`ValueError` is raised on error.
1268         """
1269
1270         value = nbt._bt_ctf_field_enumeration_get_mapping_name(self._f)
1271
1272         if value is None:
1273             raise ValueError("Could not get enumeration mapping name.")
1274
1275         return value
1276
1277     @value.setter
1278     def value(self, value):
1279         if not isinstance(value, int):
1280             raise TypeError("EnumerationField value must be an int")
1281
1282         self.container.value = value
1283
1284
1285 class FloatingPointField(Field):
1286     """
1287     Floating point number field, based on a
1288     :class:`FloatingPointFieldDeclaration` object.
1289     """
1290
1291     @property
1292     def value(self):
1293         """
1294         Floating point number value (:class:`float`).
1295
1296         Set this attribute to change the floating point number field's
1297         value.
1298
1299         :exc:`ValueError` or :exc:`TypeError` are raised on error.
1300         """
1301
1302         ret, value = nbt._bt_ctf_field_floating_point_get_value(self._f)
1303
1304         if ret < 0:
1305             raise ValueError("Could not get floating point field value.")
1306
1307         return value
1308
1309     @value.setter
1310     def value(self, value):
1311         if not isinstance(value, int) and not isinstance(value, float):
1312             raise TypeError("Value must be either a float or an int")
1313
1314         ret = nbt._bt_ctf_field_floating_point_set_value(self._f, float(value))
1315
1316         if ret < 0:
1317             raise ValueError("Could not set floating point field value.")
1318
1319
1320 # oops!! This class is provided to ensure backward-compatibility since
1321 # a stable release publicly exposed this abomination.
1322 class FloatFieldingPoint(FloatingPointField):
1323     pass
1324
1325
1326 class StructureField(Field):
1327     """
1328     Structure field, based on a
1329     :class:`StructureFieldDeclaration` object.
1330     """
1331
1332     def field(self, field_name):
1333         """
1334         Returns the structure :class:`Field` named *field_name*.
1335
1336         :exc:`ValueError` is raised on error.
1337         """
1338
1339         native_instance = nbt._bt_ctf_field_structure_get_field(self._f,
1340                                                                 str(field_name))
1341
1342         if native_instance is None:
1343             raise ValueError("Invalid field_name provided.")
1344
1345         return Field._create_field_from_native_instance(native_instance)
1346
1347
1348 class VariantField(Field):
1349     """
1350     Variant field, based on a
1351     :class:`VariantFieldDeclaration` object.
1352     """
1353
1354     def field(self, tag):
1355         """
1356         Returns the :class:`Field` selected by the current label of
1357         *tag* (:class:`EnumerationField`).
1358
1359         :exc:`ValueError` is raised on error.
1360         """
1361
1362         native_instance = nbt._bt_ctf_field_variant_get_field(self._f, tag._f)
1363
1364         if native_instance is None:
1365             raise ValueError("Invalid tag provided.")
1366
1367         return Field._create_field_from_native_instance(native_instance)
1368
1369
1370 class ArrayField(Field):
1371     def field(self, index):
1372         """
1373         Return the array's field at position "index".
1374         """
1375
1376         native_instance = nbt._bt_ctf_field_array_get_field(self._f, index)
1377
1378         if native_instance is None:
1379             raise IndexError("Invalid index provided.")
1380
1381         return Field._create_field_from_native_instance(native_instance)
1382
1383
1384 class SequenceField(Field):
1385     @property
1386     def length(self):
1387         """
1388         Get the sequence's length field (IntegerField).
1389         """
1390
1391         native_instance = nbt._bt_ctf_field_sequence_get_length(self._f)
1392
1393         if native_instance is None:
1394             length = -1
1395
1396         return Field._create_field_from_native_instance(native_instance)
1397
1398     @length.setter
1399     def length(self, length_field):
1400         """
1401         Set the sequence's length field (IntegerField).
1402         """
1403
1404         if not isinstance(length_field, IntegerField):
1405             raise TypeError("Invalid length field.")
1406
1407         if length_field.declaration.signed:
1408             raise TypeError("Sequence field length must be unsigned")
1409
1410         ret = nbt._bt_ctf_field_sequence_set_length(self._f, length_field._f)
1411
1412         if ret < 0:
1413             raise ValueError("Could not set sequence length.")
1414
1415     def field(self, index):
1416         """
1417         Return the sequence's field at position "index".
1418         """
1419
1420         native_instance = nbt._bt_ctf_field_sequence_get_field(self._f, index)
1421
1422         if native_instance is None:
1423             raise ValueError("Could not get sequence element at index.")
1424
1425         return Field._create_field_from_native_instance(native_instance)
1426
1427
1428 class StringField(Field):
1429     @property
1430     def value(self):
1431         """
1432         Get a string field's value.
1433         """
1434
1435         return nbt._bt_ctf_field_string_get_value(self._f)
1436
1437     @value.setter
1438     def value(self, value):
1439         """
1440         Set a string field's value.
1441         """
1442
1443         ret = nbt._bt_ctf_field_string_set_value(self._f, str(value))
1444
1445         if ret < 0:
1446             raise ValueError("Could not set string field value.")
1447
1448
1449 class EventClass:
1450     def __init__(self, name):
1451         """
1452         Create a new event class of the given name.
1453         """
1454
1455         self._ec = nbt._bt_ctf_event_class_create(name)
1456
1457         if self._ec is None:
1458             raise ValueError("Event class creation failed.")
1459
1460     def __del__(self):
1461         nbt._bt_ctf_event_class_put(self._ec)
1462
1463     def add_field(self, field_type, field_name):
1464         """
1465         Add a field of type "field_type" to the event class.
1466         """
1467
1468         ret = nbt._bt_ctf_event_class_add_field(self._ec, field_type._ft,
1469                                                 str(field_name))
1470
1471         if ret < 0:
1472             raise ValueError("Could not add field to event class.")
1473
1474     @property
1475     def name(self):
1476         """
1477         Get the event class' name.
1478         """
1479
1480         name = nbt._bt_ctf_event_class_get_name(self._ec)
1481
1482         if name is None:
1483             raise TypeError("Could not get EventClass name")
1484
1485         return name
1486
1487     @property
1488     def id(self):
1489         """
1490         Get the event class' id. Returns a negative value if unset.
1491         """
1492
1493         id = nbt._bt_ctf_event_class_get_id(self._ec)
1494
1495         if id < 0:
1496             raise TypeError("Could not get EventClass id")
1497
1498         return id
1499
1500     @id.setter
1501     def id(self, id):
1502         """
1503         Set the event class' id. Throws a TypeError if the event class
1504         is already registered to a stream class.
1505         """
1506
1507         ret = nbt._bt_ctf_event_class_set_id(self._ec, id)
1508
1509         if ret < 0:
1510             raise TypeError("Can't change an Event Class's id after it has been assigned to a stream class")
1511
1512     @property
1513     def stream_class(self):
1514         """
1515         Get the event class' stream class. Returns None if unset.
1516         """
1517         stream_class_native = nbt._bt_ctf_event_class_get_stream_class(self._ec)
1518
1519         if stream_class_native is None:
1520             return None
1521
1522         stream_class = StreamClass.__new__(StreamClass)
1523         stream_class._sc = stream_class_native
1524
1525         return stream_class
1526
1527     @property
1528     def fields(self):
1529         """
1530         Generator returning the event class' fields as tuples of (field name, field declaration).
1531         """
1532
1533         count = nbt._bt_ctf_event_class_get_field_count(self._ec)
1534
1535         if count < 0:
1536             raise TypeError("Could not get EventClass' field count")
1537
1538         for i in range(count):
1539             field_name = nbt._bt_python_ctf_event_class_get_field_name(self._ec, i)
1540
1541             if field_name is None:
1542                 msg = "Could not get EventClass' field name at index {}".format(i)
1543                 raise TypeError(msg)
1544
1545             field_type_native = nbt._bt_python_ctf_event_class_get_field_type(self._ec, i)
1546
1547             if field_type_native is None:
1548                 msg = "Could not get EventClass' field type at index {}".format(i)
1549                 raise TypeError(msg)
1550
1551             field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1552             yield (field_name, field_type)
1553
1554     def get_field_by_name(self, name):
1555         """
1556         Get a field declaration by name (FieldDeclaration).
1557         """
1558
1559         field_type_native = nbt._bt_ctf_event_class_get_field_by_name(self._ec, name)
1560
1561         if field_type_native is None:
1562             msg = "Could not find EventClass field with name {}".format(name)
1563             raise TypeError(msg)
1564
1565         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1566
1567
1568 class Event:
1569     def __init__(self, event_class):
1570         """
1571         Create a new event of the given event class.
1572         """
1573
1574         if not isinstance(event_class, EventClass):
1575             raise TypeError("Invalid event_class argument.")
1576
1577         self._e = nbt._bt_ctf_event_create(event_class._ec)
1578
1579         if self._e is None:
1580             raise ValueError("Event creation failed.")
1581
1582     def __del__(self):
1583         nbt._bt_ctf_event_put(self._e)
1584
1585     @property
1586     def event_class(self):
1587         """
1588         Get the event's class.
1589         """
1590
1591         event_class_native = nbt._bt_ctf_event_get_class(self._e)
1592
1593         if event_class_native is None:
1594             return None
1595
1596         event_class = EventClass.__new__(EventClass)
1597         event_class._ec = event_class_native
1598
1599         return event_class
1600
1601     def clock(self):
1602         """
1603         Get a clock from event. Returns None if the event's class
1604         is not registered to a stream class.
1605         """
1606
1607         clock_instance = nbt._bt_ctf_event_get_clock(self._e)
1608
1609         if clock_instance is None:
1610             return None
1611
1612         clock = Clock.__new__(Clock)
1613         clock._c = clock_instance
1614
1615         return clock
1616
1617     def payload(self, field_name):
1618         """
1619         Get a field from event.
1620         """
1621
1622         native_instance = nbt._bt_ctf_event_get_payload(self._e,
1623                                                         str(field_name))
1624
1625         if native_instance is None:
1626             raise ValueError("Could not get event payload.")
1627
1628         return Field._create_field_from_native_instance(native_instance)
1629
1630     def set_payload(self, field_name, value_field):
1631         """
1632         Set a manually created field as an event's payload.
1633         """
1634
1635         if not isinstance(value, Field):
1636             raise TypeError("Invalid value type.")
1637
1638         ret = nbt._bt_ctf_event_set_payload(self._e, str(field_name),
1639                                             value_field._f)
1640
1641         if ret < 0:
1642             raise ValueError("Could not set event field payload.")
1643
1644
1645 class StreamClass:
1646     def __init__(self, name):
1647         """
1648         Create a new stream class of the given name.
1649         """
1650
1651         self._sc = nbt._bt_ctf_stream_class_create(name)
1652
1653         if self._sc is None:
1654             raise ValueError("Stream class creation failed.")
1655
1656     def __del__(self):
1657         nbt._bt_ctf_stream_class_put(self._sc)
1658
1659     @property
1660     def name(self):
1661         """
1662         Get a stream class' name.
1663         """
1664
1665         name = nbt._bt_ctf_stream_class_get_name(self._sc)
1666
1667         if name is None:
1668             raise TypeError("Could not get StreamClass name")
1669
1670         return name
1671
1672     @property
1673     def clock(self):
1674         """
1675         Get a stream class' clock.
1676         """
1677
1678         clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc)
1679
1680         if clock_instance is None:
1681             return None
1682
1683         clock = Clock.__new__(Clock)
1684         clock._c = clock_instance
1685
1686         return clock
1687
1688     @clock.setter
1689     def clock(self, clock):
1690         """
1691         Assign a clock to a stream class.
1692         """
1693
1694         if not isinstance(clock, Clock):
1695             raise TypeError("Invalid clock type.")
1696
1697         ret = nbt._bt_ctf_stream_class_set_clock(self._sc, clock._c)
1698
1699         if ret < 0:
1700             raise ValueError("Could not set stream class clock.")
1701
1702     @property
1703     def id(self):
1704         """
1705         Get a stream class' id.
1706         """
1707
1708         ret = nbt._bt_ctf_stream_class_get_id(self._sc)
1709
1710         if ret < 0:
1711             raise TypeError("Could not get StreamClass id")
1712
1713         return ret
1714
1715     @id.setter
1716     def id(self, id):
1717         """
1718         Assign an id to a stream class.
1719         """
1720
1721         ret = nbt._bt_ctf_stream_class_set_id(self._sc, id)
1722
1723         if ret < 0:
1724             raise TypeError("Could not set stream class id.")
1725
1726     @property
1727     def event_classes(self):
1728         """
1729         Generator returning the stream class' event classes.
1730         """
1731
1732         count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc)
1733
1734         if count < 0:
1735             raise TypeError("Could not get StreamClass' event class count")
1736
1737         for i in range(count):
1738             event_class_native = nbt._bt_ctf_stream_class_get_event_class(self._sc, i)
1739
1740             if event_class_native is None:
1741                 msg = "Could not get StreamClass' event class at index {}".format(i)
1742                 raise TypeError(msg)
1743
1744             event_class = EventClass.__new__(EventClass)
1745             event_class._ec = event_class_native
1746             yield event_class
1747
1748     def add_event_class(self, event_class):
1749         """
1750         Add an event class to a stream class. New events can be added even after a
1751         stream has been instantiated and events have been appended. However, a stream
1752         will not accept events of a class that has not been added to the stream
1753         class beforehand.
1754         """
1755
1756         if not isinstance(event_class, EventClass):
1757             raise TypeError("Invalid event_class type.")
1758
1759         ret = nbt._bt_ctf_stream_class_add_event_class(self._sc,
1760                                                        event_class._ec)
1761
1762         if ret < 0:
1763             raise ValueError("Could not add event class.")
1764
1765     @property
1766     def packet_context_type(self):
1767         """
1768         Get the StreamClass' packet context type (StructureFieldDeclaration)
1769         """
1770
1771         field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc)
1772
1773         if field_type_native is None:
1774             raise ValueError("Invalid StreamClass")
1775
1776         field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1777
1778         return field_type
1779
1780     @packet_context_type.setter
1781     def packet_context_type(self, field_type):
1782         """
1783         Set a StreamClass' packet context type. Must be of type
1784         StructureFieldDeclaration.
1785         """
1786
1787         if not isinstance(field_type, StructureFieldDeclaration):
1788             raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
1789
1790         ret = nbt._bt_ctf_stream_class_set_packet_context_type(self._sc,
1791                                                                field_type._ft)
1792
1793         if ret < 0:
1794             raise ValueError("Failed to set packet context type.")
1795
1796
1797 class Stream:
1798     def __init__(self):
1799         raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
1800
1801     def __del__(self):
1802         nbt._bt_ctf_stream_put(self._s)
1803
1804     @property
1805     def discarded_events(self):
1806         """
1807         Get a stream's discarded event count.
1808         """
1809
1810         ret, count = nbt._bt_ctf_stream_get_discarded_events_count(self._s)
1811
1812         if ret < 0:
1813             raise ValueError("Could not get the stream's discarded events count")
1814
1815         return count
1816
1817     def append_discarded_events(self, event_count):
1818         """
1819         Increase the current packet's discarded event count.
1820         """
1821
1822         nbt._bt_ctf_stream_append_discarded_events(self._s, event_count)
1823
1824     def append_event(self, event):
1825         """
1826         Append "event" to the stream's current packet. The stream's associated clock
1827         will be sampled during this call. The event shall not be modified after
1828         being appended to a stream.
1829         """
1830
1831         ret = nbt._bt_ctf_stream_append_event(self._s, event._e)
1832
1833         if ret < 0:
1834             raise ValueError("Could not append event to stream.")
1835
1836     @property
1837     def packet_context(self):
1838         """
1839         Get a Stream's packet context field (a StructureField).
1840         """
1841
1842         native_field = nbt._bt_ctf_stream_get_packet_context(self._s)
1843
1844         if native_field is None:
1845             raise ValueError("Invalid Stream.")
1846
1847         return Field._create_field_from_native_instance(native_field)
1848
1849     @packet_context.setter
1850     def packet_context(self, field):
1851         """
1852         Set a Stream's packet context field (must be a StructureField).
1853         """
1854
1855         if not isinstance(field, StructureField):
1856             raise TypeError("Argument field must be of type StructureField")
1857
1858         ret = nbt._bt_ctf_stream_set_packet_context(self._s, field._f)
1859
1860         if ret < 0:
1861             raise ValueError("Invalid packet context field.")
1862
1863     def flush(self):
1864         """
1865         The stream's current packet's events will be flushed to disk. Events
1866         subsequently appended to the stream will be added to a new packet.
1867         """
1868
1869         ret = nbt._bt_ctf_stream_flush(self._s)
1870
1871         if ret < 0:
1872             raise ValueError("Could not flush stream.")
1873
1874
1875 class Writer:
1876     def __init__(self, path):
1877         """
1878         Create a new writer that will produce a trace in the given path.
1879         """
1880
1881         self._w = nbt._bt_ctf_writer_create(path)
1882
1883         if self._w is None:
1884             raise ValueError("Writer creation failed.")
1885
1886     def __del__(self):
1887         nbt._bt_ctf_writer_put(self._w)
1888
1889     def create_stream(self, stream_class):
1890         """
1891         Create a new stream instance and register it to the writer.
1892         """
1893
1894         if not isinstance(stream_class, StreamClass):
1895             raise TypeError("Invalid stream_class type.")
1896
1897         stream = Stream.__new__(Stream)
1898         stream._s = nbt._bt_ctf_writer_create_stream(self._w, stream_class._sc)
1899
1900         return stream
1901
1902     def add_environment_field(self, name, value):
1903         """
1904         Add an environment field to the trace.
1905         """
1906
1907         ret = nbt._bt_ctf_writer_add_environment_field(self._w, str(name),
1908                                                        str(value))
1909
1910         if ret < 0:
1911             raise ValueError("Could not add environment field to trace.")
1912
1913     def add_clock(self, clock):
1914         """
1915         Add a clock to the trace. Clocks assigned to stream classes must be
1916         registered to the writer.
1917         """
1918
1919         ret = nbt._bt_ctf_writer_add_clock(self._w, clock._c)
1920
1921         if ret < 0:
1922             raise ValueError("Could not add clock to Writer.")
1923
1924     @property
1925     def metadata(self):
1926         """
1927         Get the trace's TSDL meta-data.
1928         """
1929
1930         return nbt._bt_ctf_writer_get_metadata_string(self._w)
1931
1932     def flush_metadata(self):
1933         """
1934         Flush the trace's metadata to the metadata file.
1935         """
1936
1937         nbt._bt_ctf_writer_flush_metadata(self._w)
1938
1939     @property
1940     def byte_order(self):
1941         """
1942         Get the trace's byte order. Must be a constant from the ByteOrder
1943         class.
1944         """
1945
1946         raise NotImplementedError("Getter not implemented.")
1947
1948     @byte_order.setter
1949     def byte_order(self, byte_order):
1950         """
1951         Set the trace's byte order. Must be a constant from the ByteOrder
1952         class. Defaults to the host machine's endianness
1953         """
1954
1955         ret = nbt._bt_ctf_writer_set_byte_order(self._w, byte_order)
1956
1957         if ret < 0:
1958             raise ValueError("Could not set trace's byte order.")