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     @property
1191     def value(self):
1192         """
1193         Get an integer field's value.
1194         """
1195
1196         signedness = nbt._bt_python_field_integer_get_signedness(self._f)
1197
1198         if signedness < 0:
1199             raise TypeError("Invalid integer instance.")
1200
1201         if signedness == 0:
1202             ret, value = nbt._bt_ctf_field_unsigned_integer_get_value(self._f)
1203         else:
1204             ret, value = nbt._bt_ctf_field_signed_integer_get_value(self._f)
1205
1206         if ret < 0:
1207             raise ValueError("Could not get integer field value.")
1208
1209         return value
1210
1211     @value.setter
1212     def value(self, value):
1213         """
1214         Set an integer field's value.
1215         """
1216
1217         if not isinstance(value, int):
1218             raise TypeError("IntegerField's value must be an int")
1219
1220         signedness = nbt._bt_python_field_integer_get_signedness(self._f)
1221         if signedness < 0:
1222             raise TypeError("Invalid integer instance.")
1223
1224         if signedness == 0:
1225             ret = nbt._bt_ctf_field_unsigned_integer_set_value(self._f, value)
1226         else:
1227             ret = nbt._bt_ctf_field_signed_integer_set_value(self._f, value)
1228
1229         if ret < 0:
1230             raise ValueError("Could not set integer field value.")
1231
1232
1233 class EnumerationField(Field):
1234     @property
1235     def container(self):
1236         """
1237         Return the enumeration's underlying container field (an integer field).
1238         """
1239
1240         container = IntegerField.__new__(IntegerField)
1241         container._f = nbt._bt_ctf_field_enumeration_get_container(self._f)
1242
1243         if container._f is None:
1244             raise TypeError("Invalid enumeration field type.")
1245
1246         return container
1247
1248     @property
1249     def value(self):
1250         """
1251         Get the enumeration field's mapping name.
1252         """
1253
1254         value = nbt._bt_ctf_field_enumeration_get_mapping_name(self._f)
1255
1256         if value is None:
1257             raise ValueError("Could not get enumeration's mapping name.")
1258
1259         return value
1260
1261     @value.setter
1262     def value(self, value):
1263         """
1264         Set the enumeration field's value. Must be an integer as mapping names
1265         may be ambiguous.
1266         """
1267
1268         if not isinstance(value, int):
1269             raise TypeError("EnumerationField value must be an int")
1270
1271         self.container.value = value
1272
1273
1274 class FloatingPointField(Field):
1275     @property
1276     def value(self):
1277         """
1278         Get a floating point field's value.
1279         """
1280
1281         ret, value = nbt._bt_ctf_field_floating_point_get_value(self._f)
1282
1283         if ret < 0:
1284             raise ValueError("Could not get floating point field value.")
1285
1286         return value
1287
1288     @value.setter
1289     def value(self, value):
1290         """
1291         Set a floating point field's value.
1292         """
1293
1294         if not isinstance(value, int) and not isinstance(value, float):
1295             raise TypeError("Value must be either a float or an int")
1296
1297         ret = nbt._bt_ctf_field_floating_point_set_value(self._f, float(value))
1298
1299         if ret < 0:
1300             raise ValueError("Could not set floating point field value.")
1301
1302
1303 # oops!! This class is provided to ensure backward-compatibility since
1304 # a stable release publicly exposed this abomination.
1305 class FloatFieldingPoint(FloatingPointField):
1306     pass
1307
1308
1309 class StructureField(Field):
1310     def field(self, field_name):
1311         """
1312         Get the structure's field corresponding to the provided field name.
1313         """
1314
1315         native_instance = nbt._bt_ctf_field_structure_get_field(self._f,
1316                                                                 str(field_name))
1317
1318         if native_instance is None:
1319             raise ValueError("Invalid field_name provided.")
1320
1321         return Field._create_field_from_native_instance(native_instance)
1322
1323
1324 class VariantField(Field):
1325     def field(self, tag):
1326         """
1327         Return the variant's selected field. The "tag" field is the selector enum field.
1328         """
1329
1330         native_instance = nbt._bt_ctf_field_variant_get_field(self._f, tag._f)
1331
1332         if native_instance is None:
1333             raise ValueError("Invalid tag provided.")
1334
1335         return Field._create_field_from_native_instance(native_instance)
1336
1337
1338 class ArrayField(Field):
1339     def field(self, index):
1340         """
1341         Return the array's field at position "index".
1342         """
1343
1344         native_instance = nbt._bt_ctf_field_array_get_field(self._f, index)
1345
1346         if native_instance is None:
1347             raise IndexError("Invalid index provided.")
1348
1349         return Field._create_field_from_native_instance(native_instance)
1350
1351
1352 class SequenceField(Field):
1353     @property
1354     def length(self):
1355         """
1356         Get the sequence's length field (IntegerField).
1357         """
1358
1359         native_instance = nbt._bt_ctf_field_sequence_get_length(self._f)
1360
1361         if native_instance is None:
1362             length = -1
1363
1364         return Field._create_field_from_native_instance(native_instance)
1365
1366     @length.setter
1367     def length(self, length_field):
1368         """
1369         Set the sequence's length field (IntegerField).
1370         """
1371
1372         if not isinstance(length_field, IntegerField):
1373             raise TypeError("Invalid length field.")
1374
1375         if length_field.declaration.signed:
1376             raise TypeError("Sequence field length must be unsigned")
1377
1378         ret = nbt._bt_ctf_field_sequence_set_length(self._f, length_field._f)
1379
1380         if ret < 0:
1381             raise ValueError("Could not set sequence length.")
1382
1383     def field(self, index):
1384         """
1385         Return the sequence's field at position "index".
1386         """
1387
1388         native_instance = nbt._bt_ctf_field_sequence_get_field(self._f, index)
1389
1390         if native_instance is None:
1391             raise ValueError("Could not get sequence element at index.")
1392
1393         return Field._create_field_from_native_instance(native_instance)
1394
1395
1396 class StringField(Field):
1397     @property
1398     def value(self):
1399         """
1400         Get a string field's value.
1401         """
1402
1403         return nbt._bt_ctf_field_string_get_value(self._f)
1404
1405     @value.setter
1406     def value(self, value):
1407         """
1408         Set a string field's value.
1409         """
1410
1411         ret = nbt._bt_ctf_field_string_set_value(self._f, str(value))
1412
1413         if ret < 0:
1414             raise ValueError("Could not set string field value.")
1415
1416
1417 class EventClass:
1418     def __init__(self, name):
1419         """
1420         Create a new event class of the given name.
1421         """
1422
1423         self._ec = nbt._bt_ctf_event_class_create(name)
1424
1425         if self._ec is None:
1426             raise ValueError("Event class creation failed.")
1427
1428     def __del__(self):
1429         nbt._bt_ctf_event_class_put(self._ec)
1430
1431     def add_field(self, field_type, field_name):
1432         """
1433         Add a field of type "field_type" to the event class.
1434         """
1435
1436         ret = nbt._bt_ctf_event_class_add_field(self._ec, field_type._ft,
1437                                                 str(field_name))
1438
1439         if ret < 0:
1440             raise ValueError("Could not add field to event class.")
1441
1442     @property
1443     def name(self):
1444         """
1445         Get the event class' name.
1446         """
1447
1448         name = nbt._bt_ctf_event_class_get_name(self._ec)
1449
1450         if name is None:
1451             raise TypeError("Could not get EventClass name")
1452
1453         return name
1454
1455     @property
1456     def id(self):
1457         """
1458         Get the event class' id. Returns a negative value if unset.
1459         """
1460
1461         id = nbt._bt_ctf_event_class_get_id(self._ec)
1462
1463         if id < 0:
1464             raise TypeError("Could not get EventClass id")
1465
1466         return id
1467
1468     @id.setter
1469     def id(self, id):
1470         """
1471         Set the event class' id. Throws a TypeError if the event class
1472         is already registered to a stream class.
1473         """
1474
1475         ret = nbt._bt_ctf_event_class_set_id(self._ec, id)
1476
1477         if ret < 0:
1478             raise TypeError("Can't change an Event Class's id after it has been assigned to a stream class")
1479
1480     @property
1481     def stream_class(self):
1482         """
1483         Get the event class' stream class. Returns None if unset.
1484         """
1485         stream_class_native = nbt._bt_ctf_event_class_get_stream_class(self._ec)
1486
1487         if stream_class_native is None:
1488             return None
1489
1490         stream_class = StreamClass.__new__(StreamClass)
1491         stream_class._sc = stream_class_native
1492
1493         return stream_class
1494
1495     @property
1496     def fields(self):
1497         """
1498         Generator returning the event class' fields as tuples of (field name, field declaration).
1499         """
1500
1501         count = nbt._bt_ctf_event_class_get_field_count(self._ec)
1502
1503         if count < 0:
1504             raise TypeError("Could not get EventClass' field count")
1505
1506         for i in range(count):
1507             field_name = nbt._bt_python_ctf_event_class_get_field_name(self._ec, i)
1508
1509             if field_name is None:
1510                 msg = "Could not get EventClass' field name at index {}".format(i)
1511                 raise TypeError(msg)
1512
1513             field_type_native = nbt._bt_python_ctf_event_class_get_field_type(self._ec, i)
1514
1515             if field_type_native is None:
1516                 msg = "Could not get EventClass' field type at index {}".format(i)
1517                 raise TypeError(msg)
1518
1519             field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1520             yield (field_name, field_type)
1521
1522     def get_field_by_name(self, name):
1523         """
1524         Get a field declaration by name (FieldDeclaration).
1525         """
1526
1527         field_type_native = nbt._bt_ctf_event_class_get_field_by_name(self._ec, name)
1528
1529         if field_type_native is None:
1530             msg = "Could not find EventClass field with name {}".format(name)
1531             raise TypeError(msg)
1532
1533         return FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1534
1535
1536 class Event:
1537     def __init__(self, event_class):
1538         """
1539         Create a new event of the given event class.
1540         """
1541
1542         if not isinstance(event_class, EventClass):
1543             raise TypeError("Invalid event_class argument.")
1544
1545         self._e = nbt._bt_ctf_event_create(event_class._ec)
1546
1547         if self._e is None:
1548             raise ValueError("Event creation failed.")
1549
1550     def __del__(self):
1551         nbt._bt_ctf_event_put(self._e)
1552
1553     @property
1554     def event_class(self):
1555         """
1556         Get the event's class.
1557         """
1558
1559         event_class_native = nbt._bt_ctf_event_get_class(self._e)
1560
1561         if event_class_native is None:
1562             return None
1563
1564         event_class = EventClass.__new__(EventClass)
1565         event_class._ec = event_class_native
1566
1567         return event_class
1568
1569     def clock(self):
1570         """
1571         Get a clock from event. Returns None if the event's class
1572         is not registered to a stream class.
1573         """
1574
1575         clock_instance = nbt._bt_ctf_event_get_clock(self._e)
1576
1577         if clock_instance is None:
1578             return None
1579
1580         clock = Clock.__new__(Clock)
1581         clock._c = clock_instance
1582
1583         return clock
1584
1585     def payload(self, field_name):
1586         """
1587         Get a field from event.
1588         """
1589
1590         native_instance = nbt._bt_ctf_event_get_payload(self._e,
1591                                                         str(field_name))
1592
1593         if native_instance is None:
1594             raise ValueError("Could not get event payload.")
1595
1596         return Field._create_field_from_native_instance(native_instance)
1597
1598     def set_payload(self, field_name, value_field):
1599         """
1600         Set a manually created field as an event's payload.
1601         """
1602
1603         if not isinstance(value, Field):
1604             raise TypeError("Invalid value type.")
1605
1606         ret = nbt._bt_ctf_event_set_payload(self._e, str(field_name),
1607                                             value_field._f)
1608
1609         if ret < 0:
1610             raise ValueError("Could not set event field payload.")
1611
1612
1613 class StreamClass:
1614     def __init__(self, name):
1615         """
1616         Create a new stream class of the given name.
1617         """
1618
1619         self._sc = nbt._bt_ctf_stream_class_create(name)
1620
1621         if self._sc is None:
1622             raise ValueError("Stream class creation failed.")
1623
1624     def __del__(self):
1625         nbt._bt_ctf_stream_class_put(self._sc)
1626
1627     @property
1628     def name(self):
1629         """
1630         Get a stream class' name.
1631         """
1632
1633         name = nbt._bt_ctf_stream_class_get_name(self._sc)
1634
1635         if name is None:
1636             raise TypeError("Could not get StreamClass name")
1637
1638         return name
1639
1640     @property
1641     def clock(self):
1642         """
1643         Get a stream class' clock.
1644         """
1645
1646         clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc)
1647
1648         if clock_instance is None:
1649             return None
1650
1651         clock = Clock.__new__(Clock)
1652         clock._c = clock_instance
1653
1654         return clock
1655
1656     @clock.setter
1657     def clock(self, clock):
1658         """
1659         Assign a clock to a stream class.
1660         """
1661
1662         if not isinstance(clock, Clock):
1663             raise TypeError("Invalid clock type.")
1664
1665         ret = nbt._bt_ctf_stream_class_set_clock(self._sc, clock._c)
1666
1667         if ret < 0:
1668             raise ValueError("Could not set stream class clock.")
1669
1670     @property
1671     def id(self):
1672         """
1673         Get a stream class' id.
1674         """
1675
1676         ret = nbt._bt_ctf_stream_class_get_id(self._sc)
1677
1678         if ret < 0:
1679             raise TypeError("Could not get StreamClass id")
1680
1681         return ret
1682
1683     @id.setter
1684     def id(self, id):
1685         """
1686         Assign an id to a stream class.
1687         """
1688
1689         ret = nbt._bt_ctf_stream_class_set_id(self._sc, id)
1690
1691         if ret < 0:
1692             raise TypeError("Could not set stream class id.")
1693
1694     @property
1695     def event_classes(self):
1696         """
1697         Generator returning the stream class' event classes.
1698         """
1699
1700         count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc)
1701
1702         if count < 0:
1703             raise TypeError("Could not get StreamClass' event class count")
1704
1705         for i in range(count):
1706             event_class_native = nbt._bt_ctf_stream_class_get_event_class(self._sc, i)
1707
1708             if event_class_native is None:
1709                 msg = "Could not get StreamClass' event class at index {}".format(i)
1710                 raise TypeError(msg)
1711
1712             event_class = EventClass.__new__(EventClass)
1713             event_class._ec = event_class_native
1714             yield event_class
1715
1716     def add_event_class(self, event_class):
1717         """
1718         Add an event class to a stream class. New events can be added even after a
1719         stream has been instantiated and events have been appended. However, a stream
1720         will not accept events of a class that has not been added to the stream
1721         class beforehand.
1722         """
1723
1724         if not isinstance(event_class, EventClass):
1725             raise TypeError("Invalid event_class type.")
1726
1727         ret = nbt._bt_ctf_stream_class_add_event_class(self._sc,
1728                                                        event_class._ec)
1729
1730         if ret < 0:
1731             raise ValueError("Could not add event class.")
1732
1733     @property
1734     def packet_context_type(self):
1735         """
1736         Get the StreamClass' packet context type (StructureFieldDeclaration)
1737         """
1738
1739         field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc)
1740
1741         if field_type_native is None:
1742             raise ValueError("Invalid StreamClass")
1743
1744         field_type = FieldDeclaration._create_field_declaration_from_native_instance(field_type_native)
1745
1746         return field_type
1747
1748     @packet_context_type.setter
1749     def packet_context_type(self, field_type):
1750         """
1751         Set a StreamClass' packet context type. Must be of type
1752         StructureFieldDeclaration.
1753         """
1754
1755         if not isinstance(field_type, StructureFieldDeclaration):
1756             raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
1757
1758         ret = nbt._bt_ctf_stream_class_set_packet_context_type(self._sc,
1759                                                                field_type._ft)
1760
1761         if ret < 0:
1762             raise ValueError("Failed to set packet context type.")
1763
1764
1765 class Stream:
1766     def __init__(self):
1767         raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
1768
1769     def __del__(self):
1770         nbt._bt_ctf_stream_put(self._s)
1771
1772     @property
1773     def discarded_events(self):
1774         """
1775         Get a stream's discarded event count.
1776         """
1777
1778         ret, count = nbt._bt_ctf_stream_get_discarded_events_count(self._s)
1779
1780         if ret < 0:
1781             raise ValueError("Could not get the stream's discarded events count")
1782
1783         return count
1784
1785     def append_discarded_events(self, event_count):
1786         """
1787         Increase the current packet's discarded event count.
1788         """
1789
1790         nbt._bt_ctf_stream_append_discarded_events(self._s, event_count)
1791
1792     def append_event(self, event):
1793         """
1794         Append "event" to the stream's current packet. The stream's associated clock
1795         will be sampled during this call. The event shall not be modified after
1796         being appended to a stream.
1797         """
1798
1799         ret = nbt._bt_ctf_stream_append_event(self._s, event._e)
1800
1801         if ret < 0:
1802             raise ValueError("Could not append event to stream.")
1803
1804     @property
1805     def packet_context(self):
1806         """
1807         Get a Stream's packet context field (a StructureField).
1808         """
1809
1810         native_field = nbt._bt_ctf_stream_get_packet_context(self._s)
1811
1812         if native_field is None:
1813             raise ValueError("Invalid Stream.")
1814
1815         return Field._create_field_from_native_instance(native_field)
1816
1817     @packet_context.setter
1818     def packet_context(self, field):
1819         """
1820         Set a Stream's packet context field (must be a StructureField).
1821         """
1822
1823         if not isinstance(field, StructureField):
1824             raise TypeError("Argument field must be of type StructureField")
1825
1826         ret = nbt._bt_ctf_stream_set_packet_context(self._s, field._f)
1827
1828         if ret < 0:
1829             raise ValueError("Invalid packet context field.")
1830
1831     def flush(self):
1832         """
1833         The stream's current packet's events will be flushed to disk. Events
1834         subsequently appended to the stream will be added to a new packet.
1835         """
1836
1837         ret = nbt._bt_ctf_stream_flush(self._s)
1838
1839         if ret < 0:
1840             raise ValueError("Could not flush stream.")
1841
1842
1843 class Writer:
1844     def __init__(self, path):
1845         """
1846         Create a new writer that will produce a trace in the given path.
1847         """
1848
1849         self._w = nbt._bt_ctf_writer_create(path)
1850
1851         if self._w is None:
1852             raise ValueError("Writer creation failed.")
1853
1854     def __del__(self):
1855         nbt._bt_ctf_writer_put(self._w)
1856
1857     def create_stream(self, stream_class):
1858         """
1859         Create a new stream instance and register it to the writer.
1860         """
1861
1862         if not isinstance(stream_class, StreamClass):
1863             raise TypeError("Invalid stream_class type.")
1864
1865         stream = Stream.__new__(Stream)
1866         stream._s = nbt._bt_ctf_writer_create_stream(self._w, stream_class._sc)
1867
1868         return stream
1869
1870     def add_environment_field(self, name, value):
1871         """
1872         Add an environment field to the trace.
1873         """
1874
1875         ret = nbt._bt_ctf_writer_add_environment_field(self._w, str(name),
1876                                                        str(value))
1877
1878         if ret < 0:
1879             raise ValueError("Could not add environment field to trace.")
1880
1881     def add_clock(self, clock):
1882         """
1883         Add a clock to the trace. Clocks assigned to stream classes must be
1884         registered to the writer.
1885         """
1886
1887         ret = nbt._bt_ctf_writer_add_clock(self._w, clock._c)
1888
1889         if ret < 0:
1890             raise ValueError("Could not add clock to Writer.")
1891
1892     @property
1893     def metadata(self):
1894         """
1895         Get the trace's TSDL meta-data.
1896         """
1897
1898         return nbt._bt_ctf_writer_get_metadata_string(self._w)
1899
1900     def flush_metadata(self):
1901         """
1902         Flush the trace's metadata to the metadata file.
1903         """
1904
1905         nbt._bt_ctf_writer_flush_metadata(self._w)
1906
1907     @property
1908     def byte_order(self):
1909         """
1910         Get the trace's byte order. Must be a constant from the ByteOrder
1911         class.
1912         """
1913
1914         raise NotImplementedError("Getter not implemented.")
1915
1916     @byte_order.setter
1917     def byte_order(self, byte_order):
1918         """
1919         Set the trace's byte order. Must be a constant from the ByteOrder
1920         class. Defaults to the host machine's endianness
1921         """
1922
1923         ret = nbt._bt_ctf_writer_set_byte_order(self._w, byte_order)
1924
1925         if ret < 0:
1926             raise ValueError("Could not set trace's byte order.")