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('cannot create {} field class object'.format(self._NAME.lower()))
  50
  51
  52 class _IntegerFieldClass(_FieldClass):
  53     @property
  54     def field_value_range(self):
  55         size = native_bt.field_class_integer_get_field_value_range(self._ptr)
  56         assert(size >= 1)
  57         return size
  58
  59     def _field_value_range(self, size):
  60         if size < 1 or size > 64:
  61             raise ValueError("Value is outside valid range [1, 64] ({})".format(size))
  62         native_bt.field_class_integer_set_field_value_range(self._ptr, size)
  63
  64     _field_value_range = property(fset=_field_value_range)
  65
  66     @property
  67     def preferred_display_base(self):
  68         base = native_bt.field_class_integer_get_preferred_display_base(
  69             self._ptr)
  70         assert(base >= 0)
  71         return base
  72
  73     def _preferred_display_base(self, base):
  74         utils._check_uint64(base)
  75
  76         if base not in (IntegerDisplayBase.BINARY,
  77                         IntegerDisplayBase.OCTAL,
  78                         IntegerDisplayBase.DECIMAL,
  79                         IntegerDisplayBase.HEXADECIMAL):
  80             raise ValueError("Display base is not a valid IntegerDisplayBase value")
  81
  82         native_bt.field_class_integer_set_preferred_display_base(
  83             self._ptr, base)
  84
  85     _preferred_display_base = property(fset=_preferred_display_base)
  86
  87
  88 class _UnsignedIntegerFieldClass(_IntegerFieldClass):
  89     _NAME = 'Unsigned integer'
  90
  91
  92 class _SignedIntegerFieldClass(_IntegerFieldClass):
  93     _NAME = 'Signed integer'
  94
  95
  96 class _RealFieldClass(_FieldClass):
  97     _NAME = 'Real'
  98
  99     @property
 100     def is_single_precision(self):
 101         return native_bt.field_class_real_is_single_precision(self._ptr)
 102
 103     def _is_single_precision(self, is_single_precision):
 104         utils._check_bool(is_single_precision)
 105         native_bt.field_class_real_set_is_single_precision(
 106             self._ptr, is_single_precision)
 107
 108     _is_single_precision = property(fset=_is_single_precision)
 109
 110
 111 # an enumeration field class mapping does not have a reference count, so
 112 # we copy the properties here to avoid eventual memory access errors.
 113 class _EnumerationFieldClassMapping:
 114     def __init__(self, mapping_ptr):
 115         base_mapping_ptr = self._as_enumeration_field_class_mapping_ptr(mapping_ptr)
 116         self._label = native_bt.field_class_enumeration_mapping_get_label(base_mapping_ptr)
 117         assert self._label is not None
 118         ranges_ptr = self._mapping_borrow_ranges_ptr(mapping_ptr)
 119         assert ranges_ptr is not None
 120         self._ranges = self._ranges_type._create_from_ptr_and_get_ref(ranges_ptr)
 121
 122     @property
 123     def label(self):
 124         return self._label
 125
 126     @property
 127     def ranges(self):
 128         return self._ranges
 129
 130
 131 class _UnsignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 132     _ranges_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 133     _as_enumeration_field_class_mapping_ptr = staticmethod(native_bt.field_class_unsigned_enumeration_mapping_as_mapping_const)
 134     _mapping_borrow_ranges_ptr = staticmethod(native_bt.field_class_unsigned_enumeration_mapping_borrow_ranges_const)
 135
 136
 137 class _SignedEnumerationFieldClassMapping(_EnumerationFieldClassMapping):
 138     _ranges_type = bt2.integer_range_set.SignedIntegerRangeSet
 139     _as_enumeration_field_class_mapping_ptr = staticmethod(native_bt.field_class_signed_enumeration_mapping_as_mapping_const)
 140     _mapping_borrow_ranges_ptr = staticmethod(native_bt.field_class_signed_enumeration_mapping_borrow_ranges_const)
 141
 142
 143 class _EnumerationFieldClass(_IntegerFieldClass, collections.abc.Mapping):
 144     def __len__(self):
 145         count = native_bt.field_class_enumeration_get_mapping_count(self._ptr)
 146         assert count >= 0
 147         return count
 148
 149     def add_mapping(self, label, ranges):
 150         utils._check_str(label)
 151         utils._check_type(ranges, self._range_set_type)
 152
 153         if label in self:
 154             raise bt2.Error("duplicate mapping label '{}'".format(label))
 155
 156         status = self._add_mapping(self._ptr, label, ranges._ptr)
 157         utils._handle_func_status(status,
 158                                   'cannot add mapping to enumeration field class object')
 159
 160     def mappings_for_value(self, value):
 161         status, labels = self._get_mapping_labels_for_value(self._ptr, value)
 162         utils._handle_func_status(status, 'cannot get mapping labels for value {}'.format(value))
 163         return [self[label] for label in labels]
 164
 165     def __iter__(self):
 166         for idx in range(len(self)):
 167             mapping = self._get_mapping_by_index(self._ptr, idx)
 168             yield mapping.label
 169
 170     def __getitem__(self, label):
 171         utils._check_str(label)
 172         mapping = self._get_mapping_by_label(self._ptr, label)
 173
 174         if mapping is None:
 175             raise KeyError(label)
 176
 177         return mapping
 178
 179     def __iadd__(self, mappings):
 180         for label, ranges in mappings:
 181             self.add_mapping(label, ranges)
 182
 183         return self
 184
 185
 186 class _UnsignedEnumerationFieldClass(_EnumerationFieldClass, _UnsignedIntegerFieldClass):
 187     _NAME = 'Unsigned enumeration'
 188     _range_set_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 189     _add_mapping = staticmethod(native_bt.field_class_unsigned_enumeration_add_mapping)
 190
 191     @staticmethod
 192     def _get_mapping_by_index(enum_ptr, index):
 193         mapping_ptr = native_bt.field_class_unsigned_enumeration_borrow_mapping_by_index_const(enum_ptr, index)
 194         assert mapping_ptr is not None
 195         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 196
 197     @staticmethod
 198     def _get_mapping_by_label(enum_ptr, label):
 199         mapping_ptr = native_bt.field_class_unsigned_enumeration_borrow_mapping_by_label_const(enum_ptr, label)
 200
 201         if mapping_ptr is None:
 202             return
 203
 204         return _UnsignedEnumerationFieldClassMapping(mapping_ptr)
 205
 206     @staticmethod
 207     def _get_mapping_labels_for_value(enum_ptr, value):
 208         utils._check_uint64(value)
 209         return native_bt.field_class_unsigned_enumeration_get_mapping_labels_for_value(enum_ptr, value)
 210
 211
 212 class _SignedEnumerationFieldClass(_EnumerationFieldClass, _SignedIntegerFieldClass):
 213     _NAME = 'Signed enumeration'
 214     _range_set_type = bt2.integer_range_set.SignedIntegerRangeSet
 215     _add_mapping = staticmethod(native_bt.field_class_signed_enumeration_add_mapping)
 216
 217     @staticmethod
 218     def _get_mapping_by_index(enum_ptr, index):
 219         mapping_ptr = native_bt.field_class_signed_enumeration_borrow_mapping_by_index_const(enum_ptr, index)
 220         assert mapping_ptr is not None
 221         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 222
 223     @staticmethod
 224     def _get_mapping_by_label(enum_ptr, label):
 225         mapping_ptr = native_bt.field_class_signed_enumeration_borrow_mapping_by_label_const(enum_ptr, label)
 226
 227         if mapping_ptr is None:
 228             return
 229
 230         return _SignedEnumerationFieldClassMapping(mapping_ptr)
 231
 232     @staticmethod
 233     def _get_mapping_labels_for_value(enum_ptr, value):
 234         utils._check_int64(value)
 235         return native_bt.field_class_signed_enumeration_get_mapping_labels_for_value(enum_ptr, value)
 236
 237
 238 class _StringFieldClass(_FieldClass):
 239     _NAME = 'String'
 240
 241
 242 class _StructureFieldClassMember:
 243     def __init__(self, name, field_class):
 244         self._name = name
 245         self._field_class = field_class
 246
 247     @property
 248     def name(self):
 249         return self._name
 250
 251     @property
 252     def field_class(self):
 253         return self._field_class
 254
 255
 256 class _StructureFieldClass(_FieldClass, collections.abc.Mapping):
 257     _NAME = 'Structure'
 258
 259     def append_member(self, name, field_class):
 260         utils._check_str(name)
 261         utils._check_type(field_class, _FieldClass)
 262
 263         if name in self:
 264             raise bt2.Error("duplicate member name '{}'".format(name))
 265
 266         status = native_bt.field_class_structure_append_member(self._ptr, name, field_class._ptr)
 267         utils._handle_func_status(status,
 268                                   'cannot append member to structure field class object')
 269
 270     def __len__(self):
 271         count = native_bt.field_class_structure_get_member_count(self._ptr)
 272         assert count >= 0
 273         return count
 274
 275     @staticmethod
 276     def _create_member_from_ptr(member_ptr):
 277         name = native_bt.field_class_structure_member_get_name(member_ptr)
 278         assert name is not None
 279         fc_ptr = native_bt.field_class_structure_member_borrow_field_class_const(member_ptr)
 280         assert fc_ptr is not None
 281         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 282         return _StructureFieldClassMember(name, fc)
 283
 284     def __getitem__(self, key):
 285         if not isinstance(key, str):
 286             raise TypeError("key must be a 'str' object, got '{}'".format(key.__class__.__name__))
 287
 288         member_ptr = native_bt.field_class_structure_borrow_member_by_name_const(self._ptr, key)
 289
 290         if member_ptr is None:
 291             raise KeyError(key)
 292
 293         return self._create_member_from_ptr(member_ptr)
 294
 295     def __iter__(self):
 296         for idx in range(len(self)):
 297             member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(self._ptr, idx)
 298             assert member_ptr is not None
 299             yield native_bt.field_class_structure_member_get_name(member_ptr)
 300
 301     def __iadd__(self, members):
 302         for name, field_class in members:
 303             self.append_member(name, field_class)
 304
 305         return self
 306
 307     def member_at_index(self, index):
 308         utils._check_uint64(index)
 309
 310         if index >= len(self):
 311             raise IndexError
 312
 313         member_ptr = native_bt.field_class_structure_borrow_member_by_index_const(self._ptr, index)
 314         assert member_ptr is not None
 315         return self._create_member_from_ptr(member_ptr)
 316
 317
 318 class _VariantFieldClassOption:
 319     def __init__(self, name, field_class):
 320         self._name = name
 321         self._field_class = field_class
 322
 323     @property
 324     def name(self):
 325         return self._name
 326
 327     @property
 328     def field_class(self):
 329         return self._field_class
 330
 331
 332 class _VariantFieldClassWithSelectorOption(_VariantFieldClassOption):
 333     def __init__(self, name, field_class, ranges):
 334         super().__init__(name, field_class)
 335         self._ranges = ranges
 336
 337     @property
 338     def ranges(self):
 339         return self._ranges
 340
 341
 342 class _VariantFieldClass(_FieldClass, collections.abc.Mapping):
 343     _NAME = 'Variant'
 344     _borrow_option_by_name_ptr = staticmethod(native_bt.field_class_variant_borrow_option_by_name_const)
 345     _borrow_member_by_index_ptr = staticmethod(native_bt.field_class_variant_borrow_option_by_index_const)
 346
 347     @staticmethod
 348     def _as_option_ptr(opt_ptr):
 349         return opt_ptr
 350
 351     def _create_option_from_ptr(self, opt_ptr):
 352         name = native_bt.field_class_variant_option_get_name(opt_ptr)
 353         assert name is not None
 354         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(opt_ptr)
 355         assert fc_ptr is not None
 356         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 357         return _VariantFieldClassOption(name, fc)
 358
 359     def __len__(self):
 360         count = native_bt.field_class_variant_get_option_count(self._ptr)
 361         assert count >= 0
 362         return count
 363
 364     def __getitem__(self, key):
 365         if not isinstance(key, str):
 366             raise TypeError("key must be a 'str' object, got '{}'".format(key.__class__.__name__))
 367
 368         opt_ptr = self._borrow_option_by_name_ptr(self._ptr, key)
 369
 370         if opt_ptr is None:
 371             raise KeyError(key)
 372
 373         return self._create_option_from_ptr(opt_ptr)
 374
 375     def __iter__(self):
 376         for idx in range(len(self)):
 377             opt_ptr = self._borrow_member_by_index_ptr(self._ptr, idx)
 378             assert opt_ptr is not None
 379             base_opt_ptr = self._as_option_ptr(opt_ptr)
 380             yield native_bt.field_class_variant_option_get_name(base_opt_ptr)
 381
 382     def option_at_index(self, index):
 383         utils._check_uint64(index)
 384
 385         if index >= len(self):
 386             raise IndexError
 387
 388         opt_ptr = self._borrow_member_by_index_ptr(self._ptr, index)
 389         assert opt_ptr is not None
 390         return self._create_option_from_ptr(opt_ptr)
 391
 392
 393 class _VariantFieldClassWithoutSelector(_VariantFieldClass):
 394     _NAME = 'Variant (without selector)'
 395
 396     def append_option(self, name, field_class):
 397         utils._check_str(name)
 398         utils._check_type(field_class, _FieldClass)
 399
 400         if name in self:
 401             raise bt2.Error("duplicate option name '{}'".format(name))
 402
 403         status = native_bt.field_class_variant_without_selector_append_option(self._ptr, name, field_class._ptr)
 404         utils._handle_func_status(status,
 405                                   'cannot append option to variant field class object')
 406
 407     def __iadd__(self, options):
 408         for name, field_class in options:
 409             self.append_option(name, field_class)
 410
 411         return self
 412
 413
 414 class _VariantFieldClassWithSelector(_VariantFieldClass):
 415     _NAME = 'Variant (with selector)'
 416
 417     def _create_option_from_ptr(self, opt_ptr):
 418         base_opt_ptr = self._as_option_ptr(opt_ptr)
 419         name = native_bt.field_class_variant_option_get_name(base_opt_ptr)
 420         assert name is not None
 421         fc_ptr = native_bt.field_class_variant_option_borrow_field_class_const(base_opt_ptr)
 422         assert fc_ptr is not None
 423         fc = _create_field_class_from_ptr_and_get_ref(fc_ptr)
 424         range_set_ptr = self._option_borrow_ranges_ptr(opt_ptr)
 425         assert range_set_ptr is not None
 426         range_set = self._range_set_type._create_from_ptr_and_get_ref(range_set_ptr)
 427         return _VariantFieldClassWithSelectorOption(name, fc, range_set)
 428
 429     @property
 430     def selector_field_path(self):
 431         ptr = native_bt.field_class_variant_with_selector_borrow_selector_field_path_const(self._ptr)
 432
 433         if ptr is None:
 434             return
 435
 436         return bt2.field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 437
 438     def append_option(self, name, field_class, ranges):
 439         utils._check_str(name)
 440         utils._check_type(field_class, _FieldClass)
 441         utils._check_type(ranges, self._range_set_type)
 442
 443         if name in self:
 444             raise bt2.Error("duplicate option name '{}'".format(name))
 445
 446         if len(ranges) == 0:
 447             raise ValueError('range set is empty')
 448
 449         # TODO: check overlaps (precondition of self._append_option())
 450
 451         status = self._append_option(self._ptr, name, field_class._ptr, ranges._ptr)
 452         utils._handle_func_status(status,
 453                                   'cannot append option to variant field class object')
 454
 455     def __iadd__(self, options):
 456         for name, field_class, ranges in options:
 457             self.append_option(name, field_class, ranges)
 458
 459         return self
 460
 461
 462 class _VariantFieldClassWithUnsignedSelector(_VariantFieldClassWithSelector):
 463     _NAME = 'Variant (with unsigned selector)'
 464     _borrow_option_by_name_ptr = staticmethod(native_bt.field_class_variant_with_unsigned_selector_borrow_option_by_name_const)
 465     _borrow_member_by_index_ptr = staticmethod(native_bt.field_class_variant_with_unsigned_selector_borrow_option_by_index_const)
 466     _as_option_ptr = staticmethod(native_bt.field_class_variant_with_unsigned_selector_option_as_option_const)
 467     _append_option = staticmethod(native_bt.field_class_variant_with_unsigned_selector_append_option)
 468     _option_borrow_ranges_ptr = staticmethod(native_bt.field_class_variant_with_unsigned_selector_option_borrow_ranges_const)
 469     _range_set_type = bt2.integer_range_set.UnsignedIntegerRangeSet
 470
 471
 472 class _VariantFieldClassWithSignedSelector(_VariantFieldClassWithSelector):
 473     _NAME = 'Variant (with signed selector)'
 474     _borrow_option_by_name_ptr = staticmethod(native_bt.field_class_variant_with_signed_selector_borrow_option_by_name_const)
 475     _borrow_member_by_index_ptr = staticmethod(native_bt.field_class_variant_with_signed_selector_borrow_option_by_index_const)
 476     _as_option_ptr = staticmethod(native_bt.field_class_variant_with_signed_selector_option_as_option_const)
 477     _append_option = staticmethod(native_bt.field_class_variant_with_signed_selector_append_option)
 478     _option_borrow_ranges_ptr = staticmethod(native_bt.field_class_variant_with_signed_selector_option_borrow_ranges_const)
 479     _range_set_type = bt2.integer_range_set.SignedIntegerRangeSet
 480
 481
 482 class _ArrayFieldClass(_FieldClass):
 483     @property
 484     def element_field_class(self):
 485         elem_fc_ptr = native_bt.field_class_array_borrow_element_field_class_const(self._ptr)
 486         return _create_field_class_from_ptr_and_get_ref(elem_fc_ptr)
 487
 488
 489 class _StaticArrayFieldClass(_ArrayFieldClass):
 490     @property
 491     def length(self):
 492         return native_bt.field_class_static_array_get_length(self._ptr)
 493
 494
 495 class _DynamicArrayFieldClass(_ArrayFieldClass):
 496     @property
 497     def length_field_path(self):
 498         ptr = native_bt.field_class_dynamic_array_borrow_length_field_path_const(self._ptr)
 499         if ptr is None:
 500             return
 501
 502         return bt2.field_path._FieldPath._create_from_ptr_and_get_ref(ptr)
 503
 504     def _set_length_field_class(self, length_fc):
 505         utils._check_type(length_fc, _UnsignedIntegerFieldClass)
 506         status = native_bt.field_class_dynamic_array_set_length_field_class(self._ptr, length_fc._ptr)
 507         utils._handle_func_status(status,
 508                                   "cannot set dynamic array length field type")
 509
 510     _length_field_class = property(fset=_set_length_field_class)
 511
 512
 513 _FIELD_CLASS_TYPE_TO_OBJ = {
 514     native_bt.FIELD_CLASS_TYPE_UNSIGNED_INTEGER: _UnsignedIntegerFieldClass,
 515     native_bt.FIELD_CLASS_TYPE_SIGNED_INTEGER: _SignedIntegerFieldClass,
 516     native_bt.FIELD_CLASS_TYPE_REAL: _RealFieldClass,
 517     native_bt.FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION: _UnsignedEnumerationFieldClass,
 518     native_bt.FIELD_CLASS_TYPE_SIGNED_ENUMERATION: _SignedEnumerationFieldClass,
 519     native_bt.FIELD_CLASS_TYPE_STRING: _StringFieldClass,
 520     native_bt.FIELD_CLASS_TYPE_STRUCTURE: _StructureFieldClass,
 521     native_bt.FIELD_CLASS_TYPE_STATIC_ARRAY: _StaticArrayFieldClass,
 522     native_bt.FIELD_CLASS_TYPE_DYNAMIC_ARRAY: _DynamicArrayFieldClass,
 523     native_bt.FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR: _VariantFieldClassWithoutSelector,
 524     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_SELECTOR: _VariantFieldClassWithUnsignedSelector,
 525     native_bt.FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_SELECTOR: _VariantFieldClassWithSignedSelector,
 526 }