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     """
1372     Static array field, based on an
1373     :class:`ArrayFieldDeclaration` object.
1374     """
1375
1376     def field(self, index):
1377         """
1378         Returns the :class:`Field` at index *index* in this static
1379         array.
1380
1381         :exc:`IndexError` is raised on error.
1382         """
1383
1384         native_instance = nbt._bt_ctf_field_array_get_field(self._f, index)
1385
1386         if native_instance is None:
1387             raise IndexError("Invalid index provided.")
1388
1389         return Field._create_field_from_native_instance(native_instance)
1390
1391
1392 class SequenceField(Field):
1393     @property
1394     def length(self):
1395         """
1396         Get the sequence's length field (IntegerField).
1397         """
1398
1399         native_instance = nbt._bt_ctf_field_sequence_get_length(self._f)
1400
1401         if native_instance is None:
1402             length = -1
1403
1404         return Field._create_field_from_native_instance(native_instance)
1405
1406     @length.setter
1407     def length(self, length_field):
1408         """
1409         Set the sequence's length field (IntegerField).
1410         """
1411
1412         if not isinstance(length_field, IntegerField):
1413             raise TypeError("Invalid length field.")
1414
1415         if length_field.declaration.signed:
1416             raise TypeError("Sequence field length must be unsigned")
1417
1418         ret = nbt._bt_ctf_field_sequence_set_length(self._f, length_field._f)
1419
1420         if ret < 0:
1421             raise ValueError("Could not set sequence length.")
1422
1423     def field(self, index):
1424         """
1425         Return the sequence's field at position "index".
1426         """
1427
1428         native_instance = nbt._bt_ctf_field_sequence_get_field(self._f, index)
1429
1430         if native_instance is None:
1431             raise ValueError("Could not get sequence element at index.")
1432
1433         return Field._create_field_from_native_instance(native_instance)
1434
1435
1436 class StringField(Field):
1437     @property
1438     def value(self):
1439         """
1440         Get a string field's value.
1441         """
1442
1443         return nbt._bt_ctf_field_string_get_value(self._f)
1444
1445     @value.setter
1446     def value(self, value):
1447         """
1448         Set a string field's value.
1449         """
1450
1451         ret = nbt._bt_ctf_field_string_set_value(self._f, str(value))
1452
1453         if ret < 0:
1454             raise ValueError("Could not set string field value.")
1455
1456
1457 class EventClass:
1458     def __init__(self, name):
1459         """
1460         Create a new event class of the given name.
1461         """
1462
1463         self._ec = nbt._bt_ctf_event_class_create(name)
1464
1465         if self._ec is None:
1466             raise ValueError("Event class creation failed.")
1467
1468     def __del__(self):
1469         nbt._bt_ctf_event_class_put(self._ec)
1470
1471     def add_field(self, field_type, field_name):
1472         """
1473         Add a field of type "field_type" to the event class.
1474         """
1475
1476         ret = nbt._bt_ctf_event_class_add_field(self._ec, field_type._ft,
1477                                                 str(field_name))
1478
1479         if ret < 0:
1480             raise ValueError("Could not add field to event class.")
1481
1482     @property
1483     def name(self):
1484         """
1485         Get the event class' name.
1486         """
1487
1488         name = nbt._bt_ctf_event_class_get_name(self._ec)
1489
1490         if name is None:
1491             raise TypeError("Could not get EventClass name")
1492
1493         return name
1494
1495     @property
1496     def id(self):
1497         """
1498         Get the event class' id. Returns a negative value if unset.
1499         """
1500
1501         id = nbt._bt_ctf_event_class_get_id(self._ec)
1502
1503         if id < 0:
1504             raise TypeError("Could not get EventClass id")
1505
1506         return id
1507
1508     @id.setter
1509     def id(self, id):
1510         """
1511         Set the event class' id. Throws a TypeError if the event class
1512         is already registered to a stream class.
1513         """
1514
1515         ret = nbt._bt_ctf_event_class_set_id(self._ec, id)
1516
1517         if ret < 0:
1518             raise TypeError("Can't change an Event Class's id after it has been assigned to a stream class")
1519
1520     @property
1521     def stream_class(self):
1522         """
1523         Get the event class' stream class. Returns None if unset.
1524         """
1525         stream_class_native = nbt._bt_ctf_event_class_get_stream_class(self._ec)
1526
1527         if stream_class_native is None:
1528             return None
1529
1530         stream_class = StreamClass.__new__(StreamClass)
1531         stream_class._sc = stream_class_native
1532
1533         return stream_class
1534
1535     @property
1536     def fields(self):
1537         """
1538         Generator returning the event class' fields as tuples of (field name, field declaration).
1539         """
1540
1541         count = nbt._bt_ctf_event_class_get_field_count(self._ec)
1542
1543         if count < 0:
1544             raise TypeError("Could not get EventClass' field count")
1545
1546         for i in range(count):
1547             field_name = nbt._bt_python_ctf_event_class_get_field_name(self._ec, i)
1548
1549             if field_name is None:
1550                 msg = "Could not get EventClass' field name at index {}".format(i)
1551                 raise TypeError(msg)
1552
1553             field_type_native = nbt._bt_python_ctf_event_class_get_field_type(self._ec, i)
1554
1555             if field_type_native is None:
1556                 msg = "Could not get EventClass' field type at index {}".format(i)
1557                 raise TypeError(msg)
1558
1559             field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1560             yield (field_name, field_type)
1561
1562     def get_field_by_name(self, name):
1563         """
1564         Get a field declaration by name (FieldDeclaration).
1565         """
1566
1567         field_type_native = nbt._bt_ctf_event_class_get_field_by_name(self._ec, name)
1568
1569         if field_type_native is None:
1570             msg = "Could not find EventClass field with name {}".format(name)
1571             raise TypeError(msg)
1572
1573         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1574
1575
1576 class Event:
1577     def __init__(self, event_class):
1578         """
1579         Create a new event of the given event class.
1580         """
1581
1582         if not isinstance(event_class, EventClass):
1583             raise TypeError("Invalid event_class argument.")
1584
1585         self._e = nbt._bt_ctf_event_create(event_class._ec)
1586
1587         if self._e is None:
1588             raise ValueError("Event creation failed.")
1589
1590     def __del__(self):
1591         nbt._bt_ctf_event_put(self._e)
1592
1593     @property
1594     def event_class(self):
1595         """
1596         Get the event's class.
1597         """
1598
1599         event_class_native = nbt._bt_ctf_event_get_class(self._e)
1600
1601         if event_class_native is None:
1602             return None
1603
1604         event_class = EventClass.__new__(EventClass)
1605         event_class._ec = event_class_native
1606
1607         return event_class
1608
1609     def clock(self):
1610         """
1611         Get a clock from event. Returns None if the event's class
1612         is not registered to a stream class.
1613         """
1614
1615         clock_instance = nbt._bt_ctf_event_get_clock(self._e)
1616
1617         if clock_instance is None:
1618             return None
1619
1620         clock = Clock.__new__(Clock)
1621         clock._c = clock_instance
1622
1623         return clock
1624
1625     def payload(self, field_name):
1626         """
1627         Get a field from event.
1628         """
1629
1630         native_instance = nbt._bt_ctf_event_get_payload(self._e,
1631                                                         str(field_name))
1632
1633         if native_instance is None:
1634             raise ValueError("Could not get event payload.")
1635
1636         return Field._create_field_from_native_instance(native_instance)
1637
1638     def set_payload(self, field_name, value_field):
1639         """
1640         Set a manually created field as an event's payload.
1641         """
1642
1643         if not isinstance(value, Field):
1644             raise TypeError("Invalid value type.")
1645
1646         ret = nbt._bt_ctf_event_set_payload(self._e, str(field_name),
1647                                             value_field._f)
1648
1649         if ret < 0:
1650             raise ValueError("Could not set event field payload.")
1651
1652
1653 class StreamClass:
1654     def __init__(self, name):
1655         """
1656         Create a new stream class of the given name.
1657         """
1658
1659         self._sc = nbt._bt_ctf_stream_class_create(name)
1660
1661         if self._sc is None:
1662             raise ValueError("Stream class creation failed.")
1663
1664     def __del__(self):
1665         nbt._bt_ctf_stream_class_put(self._sc)
1666
1667     @property
1668     def name(self):
1669         """
1670         Get a stream class' name.
1671         """
1672
1673         name = nbt._bt_ctf_stream_class_get_name(self._sc)
1674
1675         if name is None:
1676             raise TypeError("Could not get StreamClass name")
1677
1678         return name
1679
1680     @property
1681     def clock(self):
1682         """
1683         Get a stream class' clock.
1684         """
1685
1686         clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc)
1687
1688         if clock_instance is None:
1689             return None
1690
1691         clock = Clock.__new__(Clock)
1692         clock._c = clock_instance
1693
1694         return clock
1695
1696     @clock.setter
1697     def clock(self, clock):
1698         """
1699         Assign a clock to a stream class.
1700         """
1701
1702         if not isinstance(clock, Clock):
1703             raise TypeError("Invalid clock type.")
1704
1705         ret = nbt._bt_ctf_stream_class_set_clock(self._sc, clock._c)
1706
1707         if ret < 0:
1708             raise ValueError("Could not set stream class clock.")
1709
1710     @property
1711     def id(self):
1712         """
1713         Get a stream class' id.
1714         """
1715
1716         ret = nbt._bt_ctf_stream_class_get_id(self._sc)
1717
1718         if ret < 0:
1719             raise TypeError("Could not get StreamClass id")
1720
1721         return ret
1722
1723     @id.setter
1724     def id(self, id):
1725         """
1726         Assign an id to a stream class.
1727         """
1728
1729         ret = nbt._bt_ctf_stream_class_set_id(self._sc, id)
1730
1731         if ret < 0:
1732             raise TypeError("Could not set stream class id.")
1733
1734     @property
1735     def event_classes(self):
1736         """
1737         Generator returning the stream class' event classes.
1738         """
1739
1740         count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc)
1741
1742         if count < 0:
1743             raise TypeError("Could not get StreamClass' event class count")
1744
1745         for i in range(count):
1746             event_class_native = nbt._bt_ctf_stream_class_get_event_class(self._sc, i)
1747
1748             if event_class_native is None:
1749                 msg = "Could not get StreamClass' event class at index {}".format(i)
1750                 raise TypeError(msg)
1751
1752             event_class = EventClass.__new__(EventClass)
1753             event_class._ec = event_class_native
1754             yield event_class
1755
1756     def add_event_class(self, event_class):
1757         """
1758         Add an event class to a stream class. New events can be added even after a
1759         stream has been instantiated and events have been appended. However, a stream
1760         will not accept events of a class that has not been added to the stream
1761         class beforehand.
1762         """
1763
1764         if not isinstance(event_class, EventClass):
1765             raise TypeError("Invalid event_class type.")
1766
1767         ret = nbt._bt_ctf_stream_class_add_event_class(self._sc,
1768                                                        event_class._ec)
1769
1770         if ret < 0:
1771             raise ValueError("Could not add event class.")
1772
1773     @property
1774     def packet_context_type(self):
1775         """
1776         Get the StreamClass' packet context type (StructureFieldDeclaration)
1777         """
1778
1779         field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc)
1780
1781         if field_type_native is None:
1782             raise ValueError("Invalid StreamClass")
1783
1784         field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1785
1786         return field_type
1787
1788     @packet_context_type.setter
1789     def packet_context_type(self, field_type):
1790         """
1791         Set a StreamClass' packet context type. Must be of type
1792         StructureFieldDeclaration.
1793         """
1794
1795         if not isinstance(field_type, StructureFieldDeclaration):
1796             raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
1797
1798         ret = nbt._bt_ctf_stream_class_set_packet_context_type(self._sc,
1799                                                                field_type._ft)
1800
1801         if ret < 0:
1802             raise ValueError("Failed to set packet context type.")
1803
1804
1805 class Stream:
1806     def __init__(self):
1807         raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
1808
1809     def __del__(self):
1810         nbt._bt_ctf_stream_put(self._s)
1811
1812     @property
1813     def discarded_events(self):
1814         """
1815         Get a stream's discarded event count.
1816         """
1817
1818         ret, count = nbt._bt_ctf_stream_get_discarded_events_count(self._s)
1819
1820         if ret < 0:
1821             raise ValueError("Could not get the stream's discarded events count")
1822
1823         return count
1824
1825     def append_discarded_events(self, event_count):
1826         """
1827         Increase the current packet's discarded event count.
1828         """
1829
1830         nbt._bt_ctf_stream_append_discarded_events(self._s, event_count)
1831
1832     def append_event(self, event):
1833         """
1834         Append "event" to the stream's current packet. The stream's associated clock
1835         will be sampled during this call. The event shall not be modified after
1836         being appended to a stream.
1837         """
1838
1839         ret = nbt._bt_ctf_stream_append_event(self._s, event._e)
1840
1841         if ret < 0:
1842             raise ValueError("Could not append event to stream.")
1843
1844     @property
1845     def packet_context(self):
1846         """
1847         Get a Stream's packet context field (a StructureField).
1848         """
1849
1850         native_field = nbt._bt_ctf_stream_get_packet_context(self._s)
1851
1852         if native_field is None:
1853             raise ValueError("Invalid Stream.")
1854
1855         return Field._create_field_from_native_instance(native_field)
1856
1857     @packet_context.setter
1858     def packet_context(self, field):
1859         """
1860         Set a Stream's packet context field (must be a StructureField).
1861         """
1862
1863         if not isinstance(field, StructureField):
1864             raise TypeError("Argument field must be of type StructureField")
1865
1866         ret = nbt._bt_ctf_stream_set_packet_context(self._s, field._f)
1867
1868         if ret < 0:
1869             raise ValueError("Invalid packet context field.")
1870
1871     def flush(self):
1872         """
1873         The stream's current packet's events will be flushed to disk. Events
1874         subsequently appended to the stream will be added to a new packet.
1875         """
1876
1877         ret = nbt._bt_ctf_stream_flush(self._s)
1878
1879         if ret < 0:
1880             raise ValueError("Could not flush stream.")
1881
1882
1883 class Writer:
1884     def __init__(self, path):
1885         """
1886         Create a new writer that will produce a trace in the given path.
1887         """
1888
1889         self._w = nbt._bt_ctf_writer_create(path)
1890
1891         if self._w is None:
1892             raise ValueError("Writer creation failed.")
1893
1894     def __del__(self):
1895         nbt._bt_ctf_writer_put(self._w)
1896
1897     def create_stream(self, stream_class):
1898         """
1899         Create a new stream instance and register it to the writer.
1900         """
1901
1902         if not isinstance(stream_class, StreamClass):
1903             raise TypeError("Invalid stream_class type.")
1904
1905         stream = Stream.__new__(Stream)
1906         stream._s = nbt._bt_ctf_writer_create_stream(self._w, stream_class._sc)
1907
1908         return stream
1909
1910     def add_environment_field(self, name, value):
1911         """
1912         Add an environment field to the trace.
1913         """
1914
1915         ret = nbt._bt_ctf_writer_add_environment_field(self._w, str(name),
1916                                                        str(value))
1917
1918         if ret < 0:
1919             raise ValueError("Could not add environment field to trace.")
1920
1921     def add_clock(self, clock):
1922         """
1923         Add a clock to the trace. Clocks assigned to stream classes must be
1924         registered to the writer.
1925         """
1926
1927         ret = nbt._bt_ctf_writer_add_clock(self._w, clock._c)
1928
1929         if ret < 0:
1930             raise ValueError("Could not add clock to Writer.")
1931
1932     @property
1933     def metadata(self):
1934         """
1935         Get the trace's TSDL meta-data.
1936         """
1937
1938         return nbt._bt_ctf_writer_get_metadata_string(self._w)
1939
1940     def flush_metadata(self):
1941         """
1942         Flush the trace's metadata to the metadata file.
1943         """
1944
1945         nbt._bt_ctf_writer_flush_metadata(self._w)
1946
1947     @property
1948     def byte_order(self):
1949         """
1950         Get the trace's byte order. Must be a constant from the ByteOrder
1951         class.
1952         """
1953
1954         raise NotImplementedError("Getter not implemented.")
1955
1956     @byte_order.setter
1957     def byte_order(self, byte_order):
1958         """
1959         Set the trace's byte order. Must be a constant from the ByteOrder
1960         class. Defaults to the host machine's endianness
1961         """
1962
1963         ret = nbt._bt_ctf_writer_set_byte_order(self._w, byte_order)
1964
1965         if ret < 0:
1966             raise ValueError("Could not set trace's byte order.")