src/bindings/python/bt2/bt2/field_class.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2017 Philippe Proulx <pproulx@efficios.com>
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23 from bt2 import native_bt, object, utils
  24 import collections.abc
  25 import bt2.field
  26 import bt2.field_path
  27 import bt2.integer_range_set
  28 import bt2
  29
  30
  31 def _create_field_class_from_ptr_and_get_ref(ptr):
  32     typeid = native_bt.field_class_get_type(ptr)
  33     return _FIELD_CLASS_TYPE_TO_OBJ[typeid]._create_from_ptr_and_get_ref(ptr)
  34
  35
  36 class IntegerDisplayBase:
  37     BINARY = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
  38     OCTAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
  39     DECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
  40     HEXADECIMAL = native_bt.FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
  41
  42
  43 class _FieldClass(object._SharedObject):
  44     _get_ref = staticmethod(native_bt.field_class_get_ref)
  45     _put_ref = staticmethod(native_bt.field_class_put_ref)
  46
  47     def _check_create_status(self, ptr):
  48         if ptr is None:
  49             raise bt2.CreationError(
  50                 'cannot create {} field class object'.format(self._NAME.lower())
  51             )
  52
  53
  54 class _IntegerFieldClass(_FieldClass):
  55     @property
  56     def field_value_range(self):
  57         size = native_bt.field_class_integer_get_field_value_range(self._ptr)
  58         assert size >= 1
  59         return size
  60
  61     def _field_value_range(self, size):
  62         if size < 1 or size > 64:
  63             raise ValueError("Value is outside valid range [1, 64] ({})".format(size))
  64         native_bt.field_class_integer_set_field_value_range(self._ptr, size)
  65
  66     _field_value_range = property(fset=_field_value_range)
  67
  68     @property
  69     def preferred_display_base(self):
  70         base = native_bt.field_class_integer_get_preferred_display_base(self._ptr)
  71         assert base >= 0
  72         return base
  73
  74     def _preferred_display_base(self, base):
  75         utils._check_uint64(base)
  76
  77         if base not in (
  78             IntegerDisplayBase.BINARY,
  79             IntegerDisplayBase.OCTAL,
  80             IntegerDisplayBase.DECIMAL,
  81             IntegerDisplayBase.HEXADECIMAL,
  82         ):
  83             raise ValueError("Display base is not a valid IntegerDisplayBase value")
  84
  85         native_bt.field_class_integer_set_preferred_display_base(self._ptr, base)
  86
  87     _preferred_display_base = property(fset=_preferred_display_base)
  88
  89
  90 class _UnsignedIntegerFieldClass(_IntegerFieldClass):
  91     _NAME = 'Unsigned integer'
  92
  93
  94 class _SignedIntegerFieldClass(_IntegerFieldClass):
  95     _NAME = 'Signed integer'
  96
  97
  98 class _RealFieldClass(_FieldClass):
  99     _NAME = 'Real'
 100
 101     @property
 102     def is_single_precision(self):
 103         return native_bt.field_class_real_is_single_precision(self._ptr)
 104
 105     def _is_single_precision(self, is_single_precision):
 106         utils._check_bool(is_single_precision)
 107         native_bt.field_class_real_set_is_single_precision(
 108             self._ptr, is_single_precision
 109         )
 110
 111     _is_single_precision = property(fset=_is_single_precision)
 112
 113
 114 # an enumeration field class mapping does not have a reference count, so
 115 # we copy the properties here to avoid eventual memory access errors.
 116 class _EnumerationFieldClassMapping:
 117     def __init__(self, mapping_ptr):
 118         base_mapping_ptr = self._as_enumeration_field_class_mapping_ptr(mapping_ptr)
 119         self._label = native_bt.field_class_enumeration_mapping_get_label(
 120             base_mapping_ptr
 121         )
 122         assert self._label is not None
 123         ranges_ptr = self._mapping_borrow_ranges_ptr(mapping_ptr)
 124         assert ranges_ptr is not None
 125         self._ranges = self._ranges_type._create_from_ptr_and_get_ref(ranges_ptr)
 126
 127     @property
 128     def label(self):
 129         return self._label
 130
 131     @property
 132     def ranges(self):
 133         return self._ranges
 134
 135
 136 class _UnsignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 137     _ranges_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 138     _as_enumeration_field_class_mapping_ptr = staticmethod(
 139         native_bt.field_class_unsigned_enumeration_mapping_as_mapping_const
 140     )
 141     _mapping_borrow_ranges_ptr = staticmethod(
 142         native_bt.field_class_unsigned_enumeration_mapping_borrow_ranges_const
 143     )
 144
 145
 146 class _SignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 147     _ranges_type = bt2.integer_range_set.SignedIntegerRangeSet
 148     _as_enumeration_field_class_mapping_ptr = staticmethod(
 149         native_bt.field_class_signed_enumeration_mapping_as_mapping_const
 150     )
 151     _mapping_borrow_ranges_ptr = staticmethod(
 152         native_bt.field_class_signed_enumeration_mapping_borrow_ranges_const
 153     )
 154
 155
 156 class _EnumerationFieldClass(_IntegerFieldClass, collections.abc.Mapping):
 157     def __len__(self):
 158         count = native_bt.field_class_enumeration_get_mapping_count(self._ptr)
 159         assert count >= 0
 160         return count
 161
 162     def add_mapping(self, label, ranges):
 163         utils._check_str(label)
 164         utils._check_type(ranges, self._range_set_type)
 165
 166         if label in self:
 167             raise bt2.Error("duplicate mapping label '{}'".format(label))
 168
 169         status = self._add_mapping(self._ptr, label, ranges._ptr)
 170         utils._handle_func_status(
 171             status, 'cannot add mapping to enumeration field class object'
 172         )
 173
 174     def mappings_for_value(self, value):
 175         status, labels = self._get_mapping_labels_for_value(self._ptr, value)
 176         utils._handle_func_status(
 177             status, 'cannot get mapping labels for value {}'.format(value)
 178         )
 179         return [self[label] for label in labels]
 180
 181     def __iter__(self):
 182         for idx in range(len(self)):
 183             mapping = self._get_mapping_by_index(self._ptr, idx)
 184             yield mapping.label
 185
 186     def __getitem__(self, label):
 187         utils._check_str(label)
 188         mapping = self._get_mapping_by_label(self._ptr, label)
 189
 190         if mapping is None:
 191             raise KeyError(label)
 192
 193         return mapping
 194
 195     def __iadd__(self, mappings):
 196         for label, ranges in mappings:
 197             self.add_mapping(label, ranges)
 198
 199         return self
 200
 201
 202 class _UnsignedEnumerationFieldClass(
 203     _EnumerationFieldClass, _UnsignedIntegerFieldClass
 204 ):
 205     _NAME = 'Unsigned enumeration'
 206     _range_set_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 207     _add_mapping = staticmethod(native_bt.field_class_unsigned_enumeration_add_mapping)
 208
 209     @staticmethod
 210     def _get_mapping_by_index(enum_ptr, index):
 211         mapping_ptr = native_bt.field_class_unsigned_enumeration_borrow_mapping_by_index_const(
 212             enum_ptr, index
 213         )
 214         assert mapping_ptr is not None
 215         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 216
 217     @staticmethod
 218     def _get_mapping_by_label(enum_ptr, label):
 219         mapping_ptr = native_bt.field_class_unsigned_enumeration_borrow_mapping_by_label_const(
 220             enum_ptr, label
 221         )
 222
 223         if mapping_ptr is None:
 224             return
 225
 226         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 227
 228     @staticmethod
 229     def _get_mapping_labels_for_value(enum_ptr, value):
 230         utils._check_uint64(value)
 231         return native_bt.field_class_unsigned_enumeration_get_mapping_labels_for_value(
 232             enum_ptr, value
 233         )
 234
 235
 236 class _SignedEnumerationFieldClass(_EnumerationFieldClass, _SignedIntegerFieldClass):
 237     _NAME = 'Signed enumeration'
 238     _range_set_type = bt2.integer_range_set.SignedIntegerRangeSet
 239     _add_mapping = staticmethod(native_bt.field_class_signed_enumeration_add_mapping)
 240
 241     @staticmethod
 242     def _get_mapping_by_index(enum_ptr, index):
 243         mapping_ptr = native_bt.field_class_signed_enumeration_borrow_mapping_by_index_const(
 244             enum_ptr, index
 245         )
 246         assert mapping_ptr is not None
 247         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 248
 249     @staticmethod
 250     def _get_mapping_by_label(enum_ptr, label):
 251         mapping_ptr = native_bt.field_class_signed_enumeration_borrow_mapping_by_label_const(
 252             enum_ptr, label
 253         )
 254
 255         if mapping_ptr is None:
 256             return
 257
 258         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 259
 260     @staticmethod
 261     def _get_mapping_labels_for_value(enum_ptr, value):
 262         utils._check_int64(value)
 263         return native_bt.field_class_signed_enumeration_get_mapping_labels_for_value(
 264             enum_ptr, value
 265         )
 266
 267
 268 class _StringFieldClass(_FieldClass):
 269     _NAME = 'String'
 270
 271
 272 class _StructureFieldClassMember:
 273     def __init__(self, name, field_class):
 274         self._name = name
 275         self._field_class = field_class
 276
 277     @property
 278     def name(self):
 279         return self._name
 280
 281     @property
 282     def field_class(self):
 283         return self._field_class
 284
 285
 286 class _StructureFieldClass(_FieldClass, collections.abc.Mapping):
 287     _NAME = 'Structure'
 288
 289     def append_member(self, name, field_class):
 290         utils._check_str(name)
 291         utils._check_type(field_class, _FieldClass)
 292
 293         if name in self:
 294             raise bt2.Error("duplicate member name '{}'".format(name))
 295
 296         status = native_bt.field_class_structure_append_member(
 297             self._ptr, name, field_class._ptr
 298         )
 299         utils._handle_func_status(
 300             status, 'cannot append member to structure field class object'
 301         )
 302
 303     def __len__(self):
 304         count = native_bt.field_class_structure_get_member_count(self._ptr)
 305         assert count >= 0
 306         return count
 307
 308     @staticmethod
 309     def _create_member_from_ptr(member_ptr):
 310         name = native_bt.field_class_structure_member_get_name(member_ptr)
 311         assert name is not None
 312         fc_ptr = native_bt.field_class_structure_member_borrow_field_class_const(
 313             member_ptr
 314         )
 315         assert fc_ptr is not None
 316         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 317         return _StructureFieldClassMember(name, fc)
 318
 319     def __getitem__(self, key):
 320         if not isinstance(key, str):
 321             raise TypeError(
 322                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 323             )
 324
 325         member_ptr = native_bt.field_class_structure_borrow_member_by_name_const(
 326             self._ptr, key
 327         )
 328
 329         if member_ptr is None:
 330             raise KeyError(key)
 331
 332         return self._create_member_from_ptr(member_ptr)
 333
 334     def __iter__(self):
 335         for idx in range(len(self)):
 336             member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(
 337                 self._ptr, idx
 338             )
 339             assert member_ptr is not None
 340             yield native_bt.field_class_structure_member_get_name(member_ptr)
 341
 342     def __iadd__(self, members):
 343         for name, field_class in members:
 344             self.append_member(name, field_class)
 345
 346         return self
 347
 348     def member_at_index(self, index):
 349         utils._check_uint64(index)
 350
 351         if index >= len(self):
 352             raise IndexError
 353
 354         member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(
 355             self._ptr, index
 356         )
 357         assert member_ptr is not None
 358         return self._create_member_from_ptr(member_ptr)
 359
 360
 361 class _VariantFieldClassOption:
 362     def __init__(self, name, field_class):
 363         self._name = name
 364         self._field_class = field_class
 365
 366     @property
 367     def name(self):
 368         return self._name
 369
 370     @property
 371     def field_class(self):
 372         return self._field_class
 373
 374
 375 class _VariantFieldClassWithSelectorOption(_VariantFieldClassOption):
 376     def __init__(self, name, field_class, ranges):
 377         super().__init__(name, field_class)
 378         self._ranges = ranges
 379
 380     @property
 381     def ranges(self):
 382         return self._ranges
 383
 384
 385 class _VariantFieldClass(_FieldClass, collections.abc.Mapping):
 386     _NAME = 'Variant'
 387     _borrow_option_by_name_ptr = staticmethod(
 388         native_bt.field_class_variant_borrow_option_by_name_const
 389     )
 390     _borrow_member_by_index_ptr = staticmethod(
 391         native_bt.field_class_variant_borrow_option_by_index_const
 392     )
 393
 394     @staticmethod
 395     def _as_option_ptr(opt_ptr):
 396         return opt_ptr
 397
 398     def _create_option_from_ptr(self, opt_ptr):
 399         name = native_bt.field_class_variant_option_get_name(opt_ptr)
 400         assert name is not None
 401         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(opt_ptr)
 402         assert fc_ptr is not None
 403         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 404         return _VariantFieldClassOption(name, fc)
 405
 406     def __len__(self):
 407         count = native_bt.field_class_variant_get_option_count(self._ptr)
 408         assert count >= 0
 409         return count
 410
 411     def __getitem__(self, key):
 412         if not isinstance(key, str):
 413             raise TypeError(
 414                 "key must be a 'str' object, got '{}'".format(key.__class__.__name__)
 415             )
 416
 417         opt_ptr = self._borrow_option_by_name_ptr(self._ptr, key)
 418
 419         if opt_ptr is None:
 420             raise KeyError(key)
 421
 422         return self._create_option_from_ptr(opt_ptr)
 423
 424     def __iter__(self):
 425         for idx in range(len(self)):
 426             opt_ptr = self._borrow_member_by_index_ptr(self._ptr, idx)
 427             assert opt_ptr is not None
 428             base_opt_ptr = self._as_option_ptr(opt_ptr)
 429             yield native_bt.field_class_variant_option_get_name(base_opt_ptr)
 430
 431     def option_at_index(self, index):
 432         utils._check_uint64(index)
 433
 434         if index >= len(self):
 435             raise IndexError
 436
 437         opt_ptr = self._borrow_member_by_index_ptr(self._ptr, index)
 438         assert opt_ptr is not None
 439         return self._create_option_from_ptr(opt_ptr)
 440
 441
 442 class _VariantFieldClassWithoutSelector(_VariantFieldClass):
 443     _NAME = 'Variant (without selector)'
 444
 445     def append_option(self, name, field_class):
 446         utils._check_str(name)
 447         utils._check_type(field_class, _FieldClass)
 448
 449         if name in self:
 450             raise bt2.Error("duplicate option name '{}'".format(name))
 451
 452         status = native_bt.field_class_variant_without_selector_append_option(
 453             self._ptr, name, field_class._ptr
 454         )
 455         utils._handle_func_status(
 456             status, 'cannot append option to variant field class object'
 457         )
 458
 459     def __iadd__(self, options):
 460         for name, field_class in options:
 461             self.append_option(name, field_class)
 462
 463         return self
 464
 465
 466 class _VariantFieldClassWithSelector(_VariantFieldClass):
 467     _NAME = 'Variant (with selector)'
 468
 469     def _create_option_from_ptr(self, opt_ptr):
 470         base_opt_ptr = self._as_option_ptr(opt_ptr)
 471         name = native_bt.field_class_variant_option_get_name(base_opt_ptr)
 472         assert name is not None
 473         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(
 474             base_opt_ptr
 475         )
 476         assert fc_ptr is not None
 477         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 478         range_set_ptr = self._option_borrow_ranges_ptr(opt_ptr)
 479         assert range_set_ptr is not None
 480         range_set = self._range_set_type._create_from_ptr_and_get_ref(range_set_ptr)
 481         return _VariantFieldClassWithSelectorOption(name, fc, range_set)
 482
 483     @property
 484     def selector_field_path(self):
 485         ptr = native_bt.field_class_variant_with_selector_borrow_selector_field_path_const(
 486             self._ptr
 487         )
 488
 489         if ptr is None:
 490             return
 491
 492         return bt2.field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 493
 494     def append_option(self, name, field_class, ranges):
 495         utils._check_str(name)
 496         utils._check_type(field_class, _FieldClass)
 497         utils._check_type(ranges, self._range_set_type)
 498
 499         if name in self:
 500             raise bt2.Error("duplicate option name '{}'".format(name))
 501
 502         if len(ranges) == 0:
 503             raise ValueError('range set is empty')
 504
 505         # TODO: check overlaps (precondition of self._append_option())
 506
 507         status = self._append_option(self._ptr, name, field_class._ptr, ranges._ptr)
 508         utils._handle_func_status(
 509             status, 'cannot append option to variant field class object'
 510         )
 511
 512     def __iadd__(self, options):
 513         for name, field_class, ranges in options:
 514             self.append_option(name, field_class, ranges)
 515
 516         return self
 517
 518
 519 class _VariantFieldClassWithUnsignedSelector(_VariantFieldClassWithSelector):
 520     _NAME = 'Variant (with unsigned selector)'
 521     _borrow_option_by_name_ptr = staticmethod(
 522         native_bt.field_class_variant_with_unsigned_selector_borrow_option_by_name_const
 523     )
 524     _borrow_member_by_index_ptr = staticmethod(
 525         native_bt.field_class_variant_with_unsigned_selector_borrow_option_by_index_const
 526     )
 527     _as_option_ptr = staticmethod(
 528         native_bt.field_class_variant_with_unsigned_selector_option_as_option_const
 529     )
 530     _append_option = staticmethod(
 531         native_bt.field_class_variant_with_unsigned_selector_append_option
 532     )
 533     _option_borrow_ranges_ptr = staticmethod(
 534         native_bt.field_class_variant_with_unsigned_selector_option_borrow_ranges_const
 535     )
 536     _range_set_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 537
 538
 539 class _VariantFieldClassWithSignedSelector(_VariantFieldClassWithSelector):
 540     _NAME = 'Variant (with signed selector)'
 541     _borrow_option_by_name_ptr = staticmethod(
 542         native_bt.field_class_variant_with_signed_selector_borrow_option_by_name_const
 543     )
 544     _borrow_member_by_index_ptr = staticmethod(
 545         native_bt.field_class_variant_with_signed_selector_borrow_option_by_index_const
 546     )
 547     _as_option_ptr = staticmethod(
 548         native_bt.field_class_variant_with_signed_selector_option_as_option_const
 549     )
 550     _append_option = staticmethod(
 551         native_bt.field_class_variant_with_signed_selector_append_option
 552     )
 553     _option_borrow_ranges_ptr = staticmethod(
 554         native_bt.field_class_variant_with_signed_selector_option_borrow_ranges_const
 555     )
 556     _range_set_type = bt2.integer_range_set.SignedIntegerRangeSet
 557
 558
 559 class _ArrayFieldClass(_FieldClass):
 560     @property
 561     def element_field_class(self):
 562         elem_fc_ptr = native_bt.field_class_array_borrow_element_field_class_const(
 563             self._ptr
 564         )
 565         return _create_field_class_from_ptr_and_get_ref(elem_fc_ptr)
 566
 567
 568 class _StaticArrayFieldClass(_ArrayFieldClass):
 569     @property
 570     def length(self):
 571         return native_bt.field_class_static_array_get_length(self._ptr)
 572
 573
 574 class _DynamicArrayFieldClass(_ArrayFieldClass):
 575     @property
 576     def length_field_path(self):
 577         ptr = native_bt.field_class_dynamic_array_borrow_length_field_path_const(
 578             self._ptr
 579         )
 580         if ptr is None:
 581             return
 582
 583         return bt2.field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 584
 585
 586 _FIELD_CLASS_TYPE_TO_OBJ = {
 587     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldClass,
 588     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldClass,
 589     native_bt.FIELD_CLASS_TYPE_REAL: _RealFieldClass,
 590     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldClass,
 591     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldClass,
 592     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldClass,
 593     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldClass,
 594     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldClass,
 595     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY: _DynamicArrayFieldClass,
 596     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR: _VariantFieldClassWithoutSelector,
 597     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_SELECTOR: _VariantFieldClassWithUnsignedSelector,
 598     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_SELECTOR: _VariantFieldClassWithSignedSelector,
 599 }