3 # Babeltrace writer interface Python module
5 # Copyright 2012-2015 EfficiOS Inc.
7 # Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
16 # The above copyright notice and this permission notice shall be included in
17 # all copies or substantial portions of the Software.
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
27 import babeltrace
.nativebt
as nbt
28 import babeltrace
.common
as common
32 # Used to compare to -1ULL in error checks
33 _MAX_UINT64
= 0xFFFFFFFFFFFFFFFF
36 class EnumerationMapping
:
38 Mapping from an enumeration label to a range of integers.
41 def __init__(self
, name
, start
, end
):
43 Creates an enumeration mapping, where label *name* is mapped to
44 the [*start*, *end*] range of integers (*end* is included).
46 Set *start* and *end* to the same value to create an enumeration
47 mapping to a single value.
57 A CTF clock allows the description of the system's clock topology, as
58 well as the definition of each clock's parameters.
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`).
65 def __init__(self
, name
):
67 Creates a default CTF clock named *name*.
69 :exc:`ValueError` is raised on error.
72 self
._c
= nbt
._bt
_ctf
_clock
_create
(name
)
75 raise ValueError("Invalid clock name.")
78 nbt
._bt
_ctf
_clock
_put
(self
._c
)
85 Set this attribute to change the clock's name.
87 :exc:`ValueError` is raised on error.
90 name
= nbt
._bt
_ctf
_clock
_get
_name
(self
._c
)
93 raise ValueError("Invalid clock instance.")
98 def description(self
):
100 Clock description (string).
102 Set this attribute to change the clock's description.
104 :exc:`ValueError` is raised on error.
107 return nbt
._bt
_ctf
_clock
_get
_description
(self
._c
)
110 def description(self
, desc
):
111 ret
= nbt
._bt
_ctf
_clock
_set
_description
(self
._c
, str(desc
))
114 raise ValueError("Invalid clock description.")
119 Clock frequency in Hz (integer).
121 Set this attribute to change the clock's frequency.
123 :exc:`ValueError` is raised on error.
126 freq
= nbt
._bt
_ctf
_clock
_get
_frequency
(self
._c
)
128 if freq
== _MAX_UINT64
:
129 raise ValueError("Invalid clock instance")
134 def frequency(self
, freq
):
135 ret
= nbt
._bt
_ctf
_clock
_set
_frequency
(self
._c
, freq
)
138 raise ValueError("Invalid frequency value.")
143 Clock precision in clock ticks (integer).
145 Set this attribute to change the clock's precision.
147 :exc:`ValueError` is raised on error.
150 precision
= nbt
._bt
_ctf
_clock
_get
_precision
(self
._c
)
152 if precision
== _MAX_UINT64
:
153 raise ValueError("Invalid clock instance")
158 def precision(self
, precision
):
159 ret
= nbt
._bt
_ctf
_clock
_set
_precision
(self
._c
, precision
)
162 raise ValueError("Invalid precision value.")
165 def offset_seconds(self
):
167 Clock offset in seconds since POSIX.1 Epoch (integer).
169 Set this attribute to change the clock's offset in seconds.
171 :exc:`ValueError` is raised on error.
174 ret
, offset_s
= nbt
._bt
_ctf
_clock
_get
_offset
_s
(self
._c
)
177 raise ValueError("Invalid clock instance")
181 @offset_seconds.setter
182 def offset_seconds(self
, offset_s
):
183 ret
= nbt
._bt
_ctf
_clock
_set
_offset
_s
(self
._c
, offset_s
)
186 raise ValueError("Invalid offset value.")
191 Clock offset in ticks since (POSIX.1 Epoch +
192 :attr:`offset_seconds`).
194 Set this attribute to change the clock's offset.
196 :exc:`ValueError` is raised on error.
199 ret
, offset
= nbt
._bt
_ctf
_clock
_get
_offset
(self
._c
)
202 raise ValueError("Invalid clock instance")
207 def offset(self
, offset
):
208 ret
= nbt
._bt
_ctf
_clock
_set
_offset
(self
._c
, offset
)
211 raise ValueError("Invalid offset value.")
216 ``True`` if this clock is absolute, i.e. if the clock is a
217 global reference across the other clocks of the trace.
219 Set this attribute to change the clock's absolute state
222 :exc:`ValueError` is raised on error.
225 is_absolute
= nbt
._bt
_ctf
_clock
_get
_is
_absolute
(self
._c
)
227 if is_absolute
== -1:
228 raise ValueError("Invalid clock instance")
230 return False if is_absolute
== 0 else True
233 def absolute(self
, is_absolute
):
234 ret
= nbt
._bt
_ctf
_clock
_set
_is
_absolute
(self
._c
, int(is_absolute
))
237 raise ValueError("Could not set the clock absolute attribute.")
242 Clock UUID (an :class:`uuid.UUID` object).
244 Set this attribute to change the clock's UUID.
246 :exc:`ValueError` is raised on error.
252 ret
, value
= nbt
._bt
_python
_ctf
_clock
_get
_uuid
_index
(self
._c
, i
)
255 raise ValueError("Invalid clock instance")
257 uuid_list
.append(value
)
259 return UUID(bytes
=bytes(uuid_list
))
262 def uuid(self
, uuid
):
263 uuid_bytes
= uuid
.bytes
265 if len(uuid_bytes
) != 16:
266 raise ValueError("Invalid UUID provided. UUID length must be 16 bytes")
268 for i
in range(len(uuid_bytes
)):
269 ret
= nbt
._bt
_python
_ctf
_clock
_set
_uuid
_index
(self
._c
, i
,
273 raise ValueError("Invalid clock instance")
278 Clock current time; nanoseconds (integer) since clock origin
279 (POSIX.1 Epoch + :attr:`offset_seconds` + :attr:`offset`).
281 Set this attribute to change the clock's current time.
283 :exc:`ValueError` is raised on error.
286 ret
, time
= nbt
._bt
_ctf
_clock
_get
_time
(self
._c
)
289 raise ValueError("Invalid clock instance")
294 def time(self
, time
):
295 ret
= nbt
._bt
_ctf
_clock
_set
_time
(self
._c
, time
)
298 raise ValueError("Invalid time value.")
303 Display base of an integer.
321 # keep this for backward compatibility
322 INTEGER_BASE_UNKNOWN
= -1
323 INTEGER_BASE_BINARY
= 2
324 INTEGER_BASE_OCTAL
= 8
325 INTEGER_BASE_DECIMAL
= 10
326 INTEGER_BASE_HEXADECIMAL
= 16
329 class FieldDeclaration
:
331 Base class of all field declarations. This class is not meant to
332 be instantiated by the user; use one of the concrete field
333 declaration subclasses instead.
336 class IntegerBase(IntegerBase
):
341 raise ValueError("FieldDeclaration creation failed.")
344 nbt
._bt
_ctf
_field
_type
_put
(self
._ft
)
347 def _create_field_declaration_from_native_instance(
348 native_field_declaration
):
350 common
.CTFTypeId
.INTEGER
: IntegerFieldDeclaration
,
351 common
.CTFTypeId
.FLOAT
: FloatFieldDeclaration
,
352 common
.CTFTypeId
.ENUM
: EnumerationFieldDeclaration
,
353 common
.CTFTypeId
.STRING
: StringFieldDeclaration
,
354 common
.CTFTypeId
.STRUCT
: StructureFieldDeclaration
,
355 common
.CTFTypeId
.VARIANT
: VariantFieldDeclaration
,
356 common
.CTFTypeId
.ARRAY
: ArrayFieldDeclaration
,
357 common
.CTFTypeId
.SEQUENCE
: SequenceFieldDeclaration
360 field_type_id
= nbt
._bt
_ctf
_field
_type
_get
_type
_id
(native_field_declaration
)
362 if field_type_id
== common
.CTFTypeId
.UNKNOWN
:
363 raise TypeError("Invalid field instance")
365 declaration
= Field
.__new
__(Field
)
366 declaration
._ft
= native_field_declaration
367 declaration
.__class
__ = type_dict
[field_type_id
]
374 Field alignment in bits (integer).
376 Set this attribute to change this field's alignment.
378 :exc:`ValueError` is raised on error.
381 return nbt
._bt
_ctf
_field
_type
_get
_alignment
(self
._ft
)
384 def alignment(self
, alignment
):
385 ret
= nbt
._bt
_ctf
_field
_type
_set
_alignment
(self
._ft
, alignment
)
388 raise ValueError("Invalid alignment value.")
391 def byte_order(self
):
393 Field byte order (one of :class:`babeltrace.common.ByteOrder`
396 Set this attribute to change this field's byte order.
398 :exc:`ValueError` is raised on error.
401 return nbt
._bt
_ctf
_field
_type
_get
_byte
_order
(self
._ft
)
404 def byte_order(self
, byte_order
):
405 ret
= nbt
._bt
_ctf
_field
_type
_set
_byte
_order
(self
._ft
, byte_order
)
408 raise ValueError("Could not set byte order value.")
411 class IntegerFieldDeclaration(FieldDeclaration
):
413 Integer field declaration.
416 def __init__(self
, size
):
418 Creates an integer field declaration of size *size* bits.
420 :exc:`ValueError` is raised on error.
423 self
._ft
= nbt
._bt
_ctf
_field
_type
_integer
_create
(size
)
429 Integer size in bits (integer).
431 Set this attribute to change this integer's size.
433 :exc:`ValueError` is raised on error.
436 ret
= nbt
._bt
_ctf
_field
_type
_integer
_get
_size
(self
._ft
)
439 raise ValueError("Could not get Integer size attribute.")
446 ``True`` if this integer is signed.
448 Set this attribute to change this integer's signedness
451 :exc:`ValueError` is raised on error.
454 ret
= nbt
._bt
_ctf
_field
_type
_integer
_get
_signed
(self
._ft
)
457 raise ValueError("Could not get Integer signed attribute.")
464 def signed(self
, signed
):
465 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_signed
(self
._ft
, signed
)
468 raise ValueError("Could not set Integer signed attribute.")
473 Integer display base (one of :class:`IntegerBase` constants).
475 Set this attribute to change this integer's display base.
477 :exc:`ValueError` is raised on error.
480 return nbt
._bt
_ctf
_field
_type
_integer
_get
_base
(self
._ft
)
483 def base(self
, base
):
484 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_base
(self
._ft
, base
)
487 raise ValueError("Could not set Integer base.")
492 Integer encoding (one of
493 :class:`babeltrace.common.CTFStringEncoding` constants).
495 Set this attribute to change this integer's encoding.
497 :exc:`ValueError` is raised on error.
500 return nbt
._bt
_ctf
_field
_type
_integer
_get
_encoding
(self
._ft
)
503 def encoding(self
, encoding
):
504 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_encoding
(self
._ft
, encoding
)
507 raise ValueError("Could not set Integer encoding.")
510 class EnumerationFieldDeclaration(FieldDeclaration
):
512 Enumeration field declaration. A CTF enumeration maps labels to
516 def __init__(self
, integer_type
):
518 Creates an enumeration field declaration, with *integer_type*
519 being the underlying :class:`IntegerFieldDeclaration` for storing
522 :exc:`ValueError` is raised on error.
525 isinst
= isinstance(integer_type
, IntegerFieldDeclaration
)
527 if integer_type
is None or not isinst
:
528 raise TypeError("Invalid integer container.")
530 self
._ft
= nbt
._bt
_ctf
_field
_type
_enumeration
_create
(integer_type
._ft
)
536 Underlying container (:class:`IntegerFieldDeclaration`).
538 :exc:`TypeError` is raised on error.
541 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_container
_type
(self
._ft
)
544 raise TypeError("Invalid enumeration declaration")
546 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
548 def add_mapping(self
, name
, range_start
, range_end
):
550 Adds a mapping to the enumeration field declaration, from the
551 label named *name* to range [*range_start*, *range_end*], where
552 *range_start* and *range_end* are integers included in the
555 :exc:`ValueError` is raised on error.
558 if range_start
< 0 or range_end
< 0:
559 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_add
_mapping
(self
._ft
,
564 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_add
_mapping
_unsigned
(self
._ft
,
570 raise ValueError("Could not add mapping to enumeration declaration.")
575 Generates the mappings of this enumeration field declaration
576 (:class:`EnumerationMapping` objects).
578 :exc:`TypeError` is raised on error.
581 signed
= self
.container
.signed
583 count
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_count
(self
._ft
)
585 for i
in range(count
):
587 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, i
)
589 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, i
)
592 msg
= "Could not get Enumeration mapping at index {}".format(i
)
595 name
, range_start
, range_end
= ret
596 yield EnumerationMapping(name
, range_start
, range_end
)
598 def get_mapping_by_name(self
, name
):
600 Returns the :class:`EnumerationMapping` object for the label
603 :exc:`TypeError` is raised on error.
606 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_name
(self
._ft
, name
)
611 if self
.container
.signed
:
612 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, index
)
614 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, index
)
617 msg
= "Could not get Enumeration mapping at index {}".format(i
)
620 name
, range_start
, range_end
= ret
622 return EnumerationMapping(name
, range_start
, range_end
)
624 def get_mapping_by_value(self
, value
):
626 Returns the :class:`EnumerationMapping` object for the value
629 :exc:`TypeError` is raised on error.
633 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_value
(self
._ft
, value
)
635 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_unsigned
_value
(self
._ft
, value
)
640 if self
.container
.signed
:
641 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, index
)
643 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, index
)
646 msg
= "Could not get Enumeration mapping at index {}".format(i
)
649 name
, range_start
, range_end
= ret
651 return EnumerationMapping(name
, range_start
, range_end
)
654 class FloatingPointFieldDeclaration(FieldDeclaration
):
656 Floating point number field declaration.
658 A CTF floating point number is a made of three sections: the sign
659 bit, the exponent bits, and the mantissa bits. The most significant
660 bit of the resulting binary word is the sign bit, and is included
661 in the number of mantissa bits.
664 `IEEE 754 <http://en.wikipedia.org/wiki/IEEE_floating_point>`_
665 single precision floating point number is represented on a 32-bit
666 word using an 8-bit exponent (``e``) and a 24-bit mantissa (``m``),
667 the latter count including the sign bit (``s``)::
669 s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
671 The IEEE 754 double precision floating point number uses an
672 11-bit exponent and a 53-bit mantissa.
675 #: IEEE 754 single precision floating point number exponent size
678 #: IEEE 754 double precision floating point number exponent size
681 #: IEEE 754 single precision floating point number mantissa size
684 #: IEEE 754 double precision floating point number mantissa size
689 Creates a floating point number field declaration.
691 :exc:`ValueError` is raised on error.
694 self
._ft
= nbt
._bt
_ctf
_field
_type
_floating
_point
_create
()
698 def exponent_digits(self
):
700 Floating point number exponent section size in bits (integer).
702 Set this attribute to change the floating point number's
703 exponent section's size. You may use :attr:`FLT_EXP_DIG` or
704 :attr:`DBL_EXP_DIG` for IEEE 754 floating point numbers.
706 :exc:`ValueError` is raised on error.
709 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_get
_exponent
_digits
(self
._ft
)
713 "Could not get Floating point exponent digit count")
717 @exponent_digits.setter
718 def exponent_digits(self
, exponent_digits
):
719 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_set
_exponent
_digits
(self
._ft
,
723 raise ValueError("Could not set exponent digit count.")
726 def mantissa_digits(self
):
728 Floating point number mantissa section size in bits (integer).
730 Set this attribute to change the floating point number's
731 mantissa section's size. You may use :attr:`FLT_MANT_DIG` or
732 :attr:`DBL_MANT_DIG` for IEEE 754 floating point numbers.
734 :exc:`ValueError` is raised on error.
737 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_get
_mantissa
_digits
(self
._ft
)
740 raise TypeError("Could not get Floating point mantissa digit count")
744 @mantissa_digits.setter
745 def mantissa_digits(self
, mantissa_digits
):
746 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_set
_mantissa
_digits
(self
._ft
,
750 raise ValueError("Could not set mantissa digit count.")
753 class FloatFieldDeclaration(FloatingPointFieldDeclaration
):
757 class StructureFieldDeclaration(FieldDeclaration
):
759 Structure field declaration, i.e. an ordered mapping from field
760 names to field declarations.
765 Creates an empty structure field declaration.
767 :exc:`ValueError` is raised on error.
770 self
._ft
= nbt
._bt
_ctf
_field
_type
_structure
_create
()
773 def add_field(self
, field_type
, field_name
):
775 Appends one :class:`FieldDeclaration` *field_type* named
776 *field_name* to the structure's ordered map.
778 :exc:`ValueError` is raised on error.
781 ret
= nbt
._bt
_ctf
_field
_type
_structure
_add
_field
(self
._ft
,
786 raise ValueError("Could not add field to structure.")
791 Generates the (field name, :class:`FieldDeclaration`) pairs
794 :exc:`TypeError` is raised on error.
797 count
= nbt
._bt
_ctf
_field
_type
_structure
_get
_field
_count
(self
._ft
)
800 raise TypeError("Could not get Structure field count")
802 for i
in range(count
):
803 field_name
= nbt
._bt
_python
_ctf
_field
_type
_structure
_get
_field
_name
(self
._ft
, i
)
805 if field_name
is None:
806 msg
= "Could not get Structure field name at index {}".format(i
)
809 field_type_native
= nbt
._bt
_python
_ctf
_field
_type
_structure
_get
_field
_type
(self
._ft
, i
)
811 if field_type_native
is None:
812 msg
= "Could not get Structure field type at index {}".format(i
)
815 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
816 yield (field_name
, field_type
)
818 def get_field_by_name(self
, name
):
820 Returns the :class:`FieldDeclaration` mapped to the field name
821 *name* in this structure.
823 :exc:`TypeError` is raised on error.
826 field_type_native
= nbt
._bt
_ctf
_field
_type
_structure
_get
_field
_type
_by
_name
(self
._ft
, name
)
828 if field_type_native
is None:
829 msg
= "Could not find Structure field with name {}".format(name
)
832 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
835 class VariantFieldDeclaration(FieldDeclaration
):
837 Variant field declaration.
839 A CTF variant is a dynamic selection between different fields.
840 The value of a *tag* (a CTF enumeration) determines what is the
841 current selected field. All the possible fields must be added to
842 its field declaration before using an actual variant field.
845 def __init__(self
, enum_tag
, tag_name
):
847 Creates an empty variant field declaration with tag field
848 declaration *enum_tag* (instance of
849 :class:`EnumerationFieldDeclaration`) named *tag_name*
852 :exc:`ValueError` is raised on error.
855 isinst
= isinstance(enum_tag
, EnumerationFieldDeclaration
)
856 if enum_tag
is None or not isinst
:
857 raise TypeError("Invalid tag type; must be of type EnumerationFieldDeclaration.")
859 self
._ft
= nbt
._bt
_ctf
_field
_type
_variant
_create
(enum_tag
._ft
,
866 Variant field declaration tag name.
868 :exc:`TypeError` is raised on error.
871 ret
= nbt
._bt
_ctf
_field
_type
_variant
_get
_tag
_name
(self
._ft
)
874 raise TypeError("Could not get Variant tag name")
881 Variant field declaration tag field declaration
882 (:class:`EnumerationFieldDeclaration` object).
884 :exc:`TypeError` is raised on error.
887 ret
= nbt
._bt
_ctf
_field
_type
_variant
_get
_tag
_type
(self
._ft
)
890 raise TypeError("Could not get Variant tag type")
892 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
894 def add_field(self
, field_type
, field_name
):
896 Registers the :class:`FieldDeclaration` object *field_type*
897 as the variant's selected type when the variant's tag's current
898 label is *field_name*.
900 :exc:`ValueError` is raised on error.
903 ret
= nbt
._bt
_ctf
_field
_type
_variant
_add
_field
(self
._ft
,
908 raise ValueError("Could not add field to variant.")
913 Generates the (field name, :class:`FieldDeclaration`) pairs
914 of this variant field declaration.
916 :exc:`TypeError` is raised on error.
919 count
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_count
(self
._ft
)
922 raise TypeError("Could not get Variant field count")
924 for i
in range(count
):
925 field_name
= nbt
._bt
_python
_ctf
_field
_type
_variant
_get
_field
_name
(self
._ft
, i
)
927 if field_name
is None:
928 msg
= "Could not get Variant field name at index {}".format(i
)
931 field_type_native
= nbt
._bt
_python
_ctf
_field
_type
_variant
_get
_field
_type
(self
._ft
, i
)
933 if field_type_native
is None:
934 msg
= "Could not get Variant field type at index {}".format(i
)
937 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
938 yield (field_name
, field_type
)
940 def get_field_by_name(self
, name
):
942 Returns the :class:`FieldDeclaration` selected when the
943 variant's tag's current label is *name*.
945 :exc:`TypeError` is raised on error.
948 field_type_native
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_type
_by
_name
(self
._ft
,
951 if field_type_native
is None:
952 msg
= "Could not find Variant field with name {}".format(name
)
955 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
957 def get_field_from_tag(self
, tag
):
959 Returns the :class:`FieldDeclaration` selected by the current
960 label of the :class:`EnumerationField` *tag*.
962 :exc:`TypeError` is raised on error.
965 field_type_native
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_type
_from
_tag
(self
._ft
, tag
._f
)
967 if field_type_native
is None:
968 msg
= "Could not find Variant field with tag value {}".format(tag
.value
)
971 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
974 class ArrayFieldDeclaration(FieldDeclaration
):
976 Static array field declaration.
979 def __init__(self
, element_type
, length
):
981 Creates a static array field declaration of *length*
982 elements of type *element_type* (:class:`FieldDeclaration`).
984 :exc:`ValueError` is raised on error.
987 self
._ft
= nbt
._bt
_ctf
_field
_type
_array
_create
(element_type
._ft
,
992 def element_type(self
):
994 Type of the elements of this this static array (subclass of
995 :class:`FieldDeclaration`).
997 :exc:`TypeError` is raised on error.
1000 ret
= nbt
._bt
_ctf
_field
_type
_array
_get
_element
_type
(self
._ft
)
1003 raise TypeError("Could not get Array element type")
1005 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
1010 Length of this static array (integer).
1012 :exc:`TypeError` is raised on error.
1015 ret
= nbt
._bt
_ctf
_field
_type
_array
_get
_length
(self
._ft
)
1018 raise TypeError("Could not get Array length")
1023 class SequenceFieldDeclaration(FieldDeclaration
):
1025 Sequence (dynamic array) field declaration.
1028 def __init__(self
, element_type
, length_field_name
):
1030 Creates a sequence field declaration of
1031 elements of type *element_type* (:class:`FieldDeclaration`).
1032 The length of a sequence field based on this sequence field
1033 declaration is obtained by retrieving the dynamic integer
1034 value of the field named *length_field_name*.
1036 :exc:`ValueError` is raised on error.
1039 self
._ft
= nbt
._bt
_ctf
_field
_type
_sequence
_create
(element_type
._ft
,
1040 str(length_field_name
))
1044 def element_type(self
):
1046 Type of the elements of this sequence (subclass of
1047 :class:`FieldDeclaration`).
1049 :exc:`TypeError` is raised on error.
1052 ret
= nbt
._bt
_ctf
_field
_type
_sequence
_get
_element
_type
(self
._ft
)
1055 raise TypeError("Could not get Sequence element type")
1057 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
1060 def length_field_name(self
):
1062 Name of the integer field defining the dynamic length of
1063 sequence fields based on this sequence field declaration.
1065 :exc:`TypeError` is raised on error.
1068 ret
= nbt
._bt
_ctf
_field
_type
_sequence
_get
_length
_field
_name
(self
._ft
)
1071 raise TypeError("Could not get Sequence length field name")
1076 class StringFieldDeclaration(FieldDeclaration
):
1078 String (NULL-terminated array of bytes) field declaration.
1083 Creates a string field declaration.
1085 :exc:`ValueError` is raised on error.
1088 self
._ft
= nbt
._bt
_ctf
_field
_type
_string
_create
()
1094 String encoding (one of
1095 :class:`babeltrace.common.CTFStringEncoding` constants).
1097 Set this attribute to change this string's encoding.
1099 :exc:`ValueError` is raised on error.
1102 return nbt
._bt
_ctf
_field
_type
_string
_get
_encoding
(self
._ft
)
1105 def encoding(self
, encoding
):
1106 ret
= nbt
._bt
_ctf
_field
_type
_string
_set
_encoding
(self
._ft
, encoding
)
1108 raise ValueError("Could not set string encoding.")
1112 def create_field(field_type
):
1114 Create an instance of a field.
1116 isinst
= isinstance(field_type
, FieldDeclaration
)
1118 if field_type
is None or not isinst
:
1119 raise TypeError("Invalid field_type. Type must be a FieldDeclaration-derived class.")
1121 if isinstance(field_type
, IntegerFieldDeclaration
):
1122 return IntegerField(field_type
)
1123 elif isinstance(field_type
, EnumerationFieldDeclaration
):
1124 return EnumerationField(field_type
)
1125 elif isinstance(field_type
, FloatFieldDeclaration
):
1126 return FloatingPointField(field_type
)
1127 elif isinstance(field_type
, StructureFieldDeclaration
):
1128 return StructureField(field_type
)
1129 elif isinstance(field_type
, VariantFieldDeclaration
):
1130 return VariantField(field_type
)
1131 elif isinstance(field_type
, ArrayFieldDeclaration
):
1132 return ArrayField(field_type
)
1133 elif isinstance(field_type
, SequenceFieldDeclaration
):
1134 return SequenceField(field_type
)
1135 elif isinstance(field_type
, StringFieldDeclaration
):
1136 return StringField(field_type
)
1141 Base class of all fields. This class is not meant to be
1142 instantiated by the user, and neither are its subclasses. Use
1143 :meth:`Event.payload` to access specific, concrete fields of
1147 def __init__(self
, field_type
):
1148 if not isinstance(field_type
, FieldDeclaration
):
1149 raise TypeError("Invalid field_type argument.")
1151 self
._f
= nbt
._bt
_ctf
_field
_create
(field_type
._ft
)
1154 raise ValueError("Field creation failed.")
1157 nbt
._bt
_ctf
_field
_put
(self
._f
)
1160 def _create_field_from_native_instance(native_field_instance
):
1162 common
.CTFTypeId
.INTEGER
: IntegerField
,
1163 common
.CTFTypeId
.FLOAT
: FloatingPointField
,
1164 common
.CTFTypeId
.ENUM
: EnumerationField
,
1165 common
.CTFTypeId
.STRING
: StringField
,
1166 common
.CTFTypeId
.STRUCT
: StructureField
,
1167 common
.CTFTypeId
.VARIANT
: VariantField
,
1168 common
.CTFTypeId
.ARRAY
: ArrayField
,
1169 common
.CTFTypeId
.SEQUENCE
: SequenceField
1172 field_type
= nbt
._bt
_python
_get
_field
_type
(native_field_instance
)
1174 if field_type
== common
.CTFTypeId
.UNKNOWN
:
1175 raise TypeError("Invalid field instance")
1177 field
= Field
.__new
__(Field
)
1178 field
._f
= native_field_instance
1179 field
.__class
__ = type_dict
[field_type
]
1184 def declaration(self
):
1186 Field declaration (subclass of :class:`FieldDeclaration`).
1188 :exc:`TypeError` is raised on error.
1191 native_field_type
= nbt
._bt
_ctf
_field
_get
_type
(self
._f
)
1193 if native_field_type
is None:
1194 raise TypeError("Invalid field instance")
1195 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(
1199 class IntegerField(Field
):
1201 Integer field, based on an :class:`IntegerFieldDeclaration` object.
1207 Integer value (:class:`int`).
1209 Set this attribute to change the integer field's value.
1211 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1214 signedness
= nbt
._bt
_python
_field
_integer
_get
_signedness
(self
._f
)
1217 raise TypeError("Invalid integer instance.")
1220 ret
, value
= nbt
._bt
_ctf
_field
_unsigned
_integer
_get
_value
(self
._f
)
1222 ret
, value
= nbt
._bt
_ctf
_field
_signed
_integer
_get
_value
(self
._f
)
1225 raise ValueError("Could not get integer field value.")
1230 def value(self
, value
):
1231 if not isinstance(value
, int):
1232 raise TypeError("IntegerField's value must be an int")
1234 signedness
= nbt
._bt
_python
_field
_integer
_get
_signedness
(self
._f
)
1236 raise TypeError("Invalid integer instance.")
1239 ret
= nbt
._bt
_ctf
_field
_unsigned
_integer
_set
_value
(self
._f
, value
)
1241 ret
= nbt
._bt
_ctf
_field
_signed
_integer
_set
_value
(self
._f
, value
)
1244 raise ValueError("Could not set integer field value.")
1247 class EnumerationField(Field
):
1249 Enumeration field, based on an
1250 :class:`EnumerationFieldDeclaration` object.
1254 def container(self
):
1256 Underlying container (:class:`IntegerField`).
1258 :exc:`TypeError` is raised on error.
1261 container
= IntegerField
.__new
__(IntegerField
)
1262 container
._f
= nbt
._bt
_ctf
_field
_enumeration
_get
_container
(self
._f
)
1264 if container
._f
is None:
1265 raise TypeError("Invalid enumeration field type.")
1272 Current label of this enumeration field (:class:`str`).
1274 Set this attribute to an integer (:class:`int`) to change the
1275 enumeration field's value.
1277 :exc:`ValueError` is raised on error.
1280 value
= nbt
._bt
_ctf
_field
_enumeration
_get
_mapping
_name
(self
._f
)
1283 raise ValueError("Could not get enumeration mapping name.")
1288 def value(self
, value
):
1289 if not isinstance(value
, int):
1290 raise TypeError("EnumerationField value must be an int")
1292 self
.container
.value
= value
1295 class FloatingPointField(Field
):
1297 Floating point number field, based on a
1298 :class:`FloatingPointFieldDeclaration` object.
1304 Floating point number value (:class:`float`).
1306 Set this attribute to change the floating point number field's
1309 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1312 ret
, value
= nbt
._bt
_ctf
_field
_floating
_point
_get
_value
(self
._f
)
1315 raise ValueError("Could not get floating point field value.")
1320 def value(self
, value
):
1321 if not isinstance(value
, int) and not isinstance(value
, float):
1322 raise TypeError("Value must be either a float or an int")
1324 ret
= nbt
._bt
_ctf
_field
_floating
_point
_set
_value
(self
._f
, float(value
))
1327 raise ValueError("Could not set floating point field value.")
1330 # oops!! This class is provided to ensure backward-compatibility since
1331 # a stable release publicly exposed this abomination.
1332 class FloatFieldingPoint(FloatingPointField
):
1336 class StructureField(Field
):
1338 Structure field, based on a
1339 :class:`StructureFieldDeclaration` object.
1342 def field(self
, field_name
):
1344 Returns the structure :class:`Field` named *field_name*.
1346 :exc:`ValueError` is raised on error.
1349 native_instance
= nbt
._bt
_ctf
_field
_structure
_get
_field
(self
._f
,
1352 if native_instance
is None:
1353 raise ValueError("Invalid field_name provided.")
1355 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1358 class VariantField(Field
):
1360 Variant field, based on a
1361 :class:`VariantFieldDeclaration` object.
1364 def field(self
, tag
):
1366 Returns the :class:`Field` selected by the current label of
1367 *tag* (:class:`EnumerationField`).
1369 :exc:`ValueError` is raised on error.
1372 native_instance
= nbt
._bt
_ctf
_field
_variant
_get
_field
(self
._f
, tag
._f
)
1374 if native_instance
is None:
1375 raise ValueError("Invalid tag provided.")
1377 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1380 class ArrayField(Field
):
1382 Static array field, based on an
1383 :class:`ArrayFieldDeclaration` object.
1386 def field(self
, index
):
1388 Returns the :class:`Field` at index *index* in this static
1391 :exc:`IndexError` is raised on error.
1394 native_instance
= nbt
._bt
_ctf
_field
_array
_get
_field
(self
._f
, index
)
1396 if native_instance
is None:
1397 raise IndexError("Invalid index provided.")
1399 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1402 class SequenceField(Field
):
1404 Sequence (dynamic array) field, based on a
1405 :class:`SequenceFieldDeclaration` object.
1411 Sequence length (:class:`IntegerField`).
1413 Set this attribute to change the sequence length's integer
1414 field (integer must be unsigned).
1416 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1419 native_instance
= nbt
._bt
_ctf
_field
_sequence
_get
_length
(self
._f
)
1421 if native_instance
is None:
1424 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1427 def length(self
, length_field
):
1428 if not isinstance(length_field
, IntegerField
):
1429 raise TypeError("Invalid length field.")
1431 if length_field
.declaration
.signed
:
1432 raise TypeError("Sequence field length must be unsigned")
1434 ret
= nbt
._bt
_ctf
_field
_sequence
_set
_length
(self
._f
, length_field
._f
)
1437 raise ValueError("Could not set sequence length.")
1439 def field(self
, index
):
1441 Returns the :class:`Field` at index *index* in this sequence.
1443 :exc:`ValueError` is raised on error.
1446 native_instance
= nbt
._bt
_ctf
_field
_sequence
_get
_field
(self
._f
, index
)
1448 if native_instance
is None:
1449 raise ValueError("Could not get sequence element at index.")
1451 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1454 class StringField(Field
):
1456 String (NULL-terminated array of bytes) field.
1462 String value (:class:`str`).
1464 Set this attribute to change the string's value.
1466 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1469 return nbt
._bt
_ctf
_field
_string
_get
_value
(self
._f
)
1472 def value(self
, value
):
1473 ret
= nbt
._bt
_ctf
_field
_string
_set
_value
(self
._f
, str(value
))
1476 raise ValueError("Could not set string field value.")
1481 An event class contains the properties of specific
1482 events (:class:`Event`). Any concrete event must be linked with an
1483 :class:`EventClass`.
1485 Some attributes are automatically set when creating an event class.
1486 For example, if no numeric ID is explicitly set using the
1487 :attr:`id` attribute, a default, unique ID within the stream class
1488 containing this event class will be created when needed.
1491 def __init__(self
, name
):
1493 Creates an event class named *name*.
1495 :exc:`ValueError` is raised on error.
1498 self
._ec
= nbt
._bt
_ctf
_event
_class
_create
(name
)
1500 if self
._ec
is None:
1501 raise ValueError("Event class creation failed.")
1504 nbt
._bt
_ctf
_event
_class
_put
(self
._ec
)
1506 def add_field(self
, field_type
, field_name
):
1508 Adds a field declaration *field_type* named *field_name* to
1511 *field_type* must be one of:
1513 * :class:`IntegerFieldDeclaration`
1514 * :class:`FloatingPointFieldDeclaration`
1515 * :class:`EnumerationFieldDeclaration`
1516 * :class:`StringFieldDeclaration`
1517 * :class:`ArrayFieldDeclaration`
1518 * :class:`SequenceFieldDeclaration`
1519 * :class:`StructureFieldDeclaration`
1520 * :class:`VariantFieldDeclaration`
1522 :exc:`ValueError` is raised on error.
1525 ret
= nbt
._bt
_ctf
_event
_class
_add
_field
(self
._ec
, field_type
._ft
,
1529 raise ValueError("Could not add field to event class.")
1537 name
= nbt
._bt
_ctf
_event
_class
_get
_name
(self
._ec
)
1540 raise TypeError("Could not get EventClass name")
1547 Event class' numeric ID.
1549 Set this attribute to assign a numeric ID to this event class.
1550 This ID must be unique amongst all the event class IDs of a
1553 :exc:`TypeError` is raised on error.
1556 id = nbt
._bt
_ctf
_event
_class
_get
_id
(self
._ec
)
1559 raise TypeError("Could not get EventClass id")
1565 ret
= nbt
._bt
_ctf
_event
_class
_set
_id
(self
._ec
, id)
1568 raise TypeError("Can't change an Event Class id after it has been assigned to a stream class")
1571 def stream_class(self
):
1573 :class:`StreamClass` object containing this event class,
1574 or ``None`` if not set.
1577 stream_class_native
= nbt
._bt
_ctf
_event
_class
_get
_stream
_class
(self
._ec
)
1579 if stream_class_native
is None:
1582 stream_class
= StreamClass
.__new
__(StreamClass
)
1583 stream_class
._sc
= stream_class_native
1590 Generates the (field name, :class:`FieldDeclaration`) pairs of
1593 :exc:`TypeError` is raised on error.
1596 count
= nbt
._bt
_ctf
_event
_class
_get
_field
_count
(self
._ec
)
1599 raise TypeError("Could not get EventClass' field count")
1601 for i
in range(count
):
1602 field_name
= nbt
._bt
_python
_ctf
_event
_class
_get
_field
_name
(self
._ec
, i
)
1604 if field_name
is None:
1605 msg
= "Could not get EventClass' field name at index {}".format(i
)
1606 raise TypeError(msg
)
1608 field_type_native
= nbt
._bt
_python
_ctf
_event
_class
_get
_field
_type
(self
._ec
, i
)
1610 if field_type_native
is None:
1611 msg
= "Could not get EventClass' field type at index {}".format(i
)
1612 raise TypeError(msg
)
1614 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1615 yield (field_name
, field_type
)
1617 def get_field_by_name(self
, name
):
1619 Returns the :class:`FieldDeclaration` object named *name* in
1622 :exc:`TypeError` is raised on error.
1625 field_type_native
= nbt
._bt
_ctf
_event
_class
_get
_field
_by
_name
(self
._ec
, name
)
1627 if field_type_native
is None:
1628 msg
= "Could not find EventClass field with name {}".format(name
)
1629 raise TypeError(msg
)
1631 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1636 Events are specific instances of event classes
1637 (:class:`EventClass`), which means they may contain actual,
1638 concrete field values.
1641 def __init__(self
, event_class
):
1643 Creates an event linked with the :class:`EventClass`
1646 :exc:`ValueError` is raised on error.
1649 if not isinstance(event_class
, EventClass
):
1650 raise TypeError("Invalid event_class argument.")
1652 self
._e
= nbt
._bt
_ctf
_event
_create
(event_class
._ec
)
1655 raise ValueError("Event creation failed.")
1658 nbt
._bt
_ctf
_event
_put
(self
._e
)
1661 def event_class(self
):
1663 :class:`EventClass` object to which this event is linked.
1666 event_class_native
= nbt
._bt
_ctf
_event
_get
_class
(self
._e
)
1668 if event_class_native
is None:
1671 event_class
= EventClass
.__new
__(EventClass
)
1672 event_class
._ec
= event_class_native
1678 :class:`Clock` object used by this object, or ``None`` if
1679 the event class is not registered to a stream class.
1682 clock_instance
= nbt
._bt
_ctf
_event
_get
_clock
(self
._e
)
1684 if clock_instance
is None:
1687 clock
= Clock
.__new
__(Clock
)
1688 clock
._c
= clock_instance
1692 def payload(self
, field_name
):
1694 Returns the :class:`Field` object named *field_name* in this
1697 The returned field object is created using the event class'
1698 field declaration named *field_name*.
1700 The return type is one of:
1702 * :class:`IntegerField`
1703 * :class:`FloatingPointField`
1704 * :class:`EnumerationField`
1705 * :class:`StringField`
1706 * :class:`ArrayField`
1707 * :class:`SequenceField`
1708 * :class:`StructureField`
1709 * :class:`VariantField`
1711 :exc:`TypeError` is raised on error.
1714 native_instance
= nbt
._bt
_ctf
_event
_get
_payload
(self
._e
,
1717 if native_instance
is None:
1718 raise ValueError("Could not get event payload.")
1720 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1722 def set_payload(self
, field_name
, value_field
):
1724 Set the event's field named *field_name* to the manually
1725 created :class:`Field` object *value_field*.
1727 *value_field*'s type must be one of:
1729 * :class:`IntegerField`
1730 * :class:`FloatingPointField`
1731 * :class:`EnumerationField`
1732 * :class:`StringField`
1733 * :class:`ArrayField`
1734 * :class:`SequenceField`
1735 * :class:`StructureField`
1736 * :class:`VariantField`
1738 :exc:`ValueError` is raised on error.
1741 if not isinstance(value
, Field
):
1742 raise TypeError("Invalid value type.")
1744 ret
= nbt
._bt
_ctf
_event
_set
_payload
(self
._e
, str(field_name
),
1748 raise ValueError("Could not set event field payload.")
1753 A stream class contains the properties of specific
1754 streams (:class:`Stream`). Any concrete stream must be linked with
1755 a :class:`StreamClass`, usually by calling
1756 :meth:`Writer.create_stream`.
1758 Some attributes are automatically set when creating a stream class.
1759 For example, if no clock is explicitly set using the
1760 :attr:`clock` attribute, a default clock will be created
1764 def __init__(self
, name
):
1766 Creates a stream class named *name*.
1768 :exc:`ValueError` is raised on error.
1771 self
._sc
= nbt
._bt
_ctf
_stream
_class
_create
(name
)
1773 if self
._sc
is None:
1774 raise ValueError("Stream class creation failed.")
1777 nbt
._bt
_ctf
_stream
_class
_put
(self
._sc
)
1784 :exc:`TypeError` is raised on error.
1787 name
= nbt
._bt
_ctf
_stream
_class
_get
_name
(self
._sc
)
1790 raise TypeError("Could not get StreamClass name")
1797 Stream class' clock (:class:`Clock` object).
1799 Set this attribute to change the clock of this stream class.
1801 :exc:`ValueError` is raised on error.
1804 clock_instance
= nbt
._bt
_ctf
_stream
_class
_get
_clock
(self
._sc
)
1806 if clock_instance
is None:
1809 clock
= Clock
.__new
__(Clock
)
1810 clock
._c
= clock_instance
1815 def clock(self
, clock
):
1816 if not isinstance(clock
, Clock
):
1817 raise TypeError("Invalid clock type.")
1819 ret
= nbt
._bt
_ctf
_stream
_class
_set
_clock
(self
._sc
, clock
._c
)
1822 raise ValueError("Could not set stream class clock.")
1827 Stream class' numeric ID.
1829 Set this attribute to change the ID of this stream class.
1831 :exc:`ValueError` is raised on error.
1834 ret
= nbt
._bt
_ctf
_stream
_class
_get
_id
(self
._sc
)
1837 raise TypeError("Could not get StreamClass id")
1843 ret
= nbt
._bt
_ctf
_stream
_class
_set
_id
(self
._sc
, id)
1846 raise TypeError("Could not set stream class id.")
1849 def event_classes(self
):
1851 Generates the event classes (:class:`EventClass` objects) of
1854 :exc:`TypeError` is raised on error.
1857 count
= nbt
._bt
_ctf
_stream
_class
_get
_event
_class
_count
(self
._sc
)
1860 raise TypeError("Could not get StreamClass' event class count")
1862 for i
in range(count
):
1863 event_class_native
= nbt
._bt
_ctf
_stream
_class
_get
_event
_class
(self
._sc
, i
)
1865 if event_class_native
is None:
1866 msg
= "Could not get StreamClass' event class at index {}".format(i
)
1867 raise TypeError(msg
)
1869 event_class
= EventClass
.__new
__(EventClass
)
1870 event_class
._ec
= event_class_native
1873 def add_event_class(self
, event_class
):
1875 Registers the :class:`EventClass` *event_class* to this stream
1878 Once the event class is registered, it will be generated as one
1879 of the event classes generated by :attr:`event_classes`.
1881 :exc:`ValueError` is raised on error.
1884 if not isinstance(event_class
, EventClass
):
1885 raise TypeError("Invalid event_class type.")
1887 ret
= nbt
._bt
_ctf
_stream
_class
_add
_event
_class
(self
._sc
,
1891 raise ValueError("Could not add event class.")
1894 def packet_context_type(self
):
1896 Stream packet context declaration.
1898 Set this attribute to change the stream packet context
1899 declaration (must be an instance of
1900 :class:`StructureFieldDeclaration`).
1902 :exc:`ValueError` is raised on error.
1906 field_type_native
= nbt
._bt
_ctf
_stream
_class
_get
_packet
_context
_type
(self
._sc
)
1908 if field_type_native
is None:
1909 raise ValueError("Invalid StreamClass")
1911 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1915 @packet_context_type.setter
1916 def packet_context_type(self
, field_type
):
1917 if not isinstance(field_type
, StructureFieldDeclaration
):
1918 raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
1920 ret
= nbt
._bt
_ctf
_stream
_class
_set
_packet
_context
_type
(self
._sc
,
1924 raise ValueError("Failed to set packet context type.")
1929 Streams are specific instances of stream classes, which means they
1930 may contain actual, concrete events.
1932 :class:`Stream` objects are returned by
1933 :meth:`Writer.create_stream`; they are not meant to be
1934 instantiated by the user.
1936 Concrete :class:`Event` objects are appended to
1937 :class:`Stream` objects using :meth:`append_event`.
1939 When :meth:`flush` is called, a CTF packet is created, containing
1940 all the appended events since the last flush. Although the stream
1941 is flushed on object destruction, it is **strongly recommended**
1942 that the user call :meth:`flush` manually before exiting the
1943 script, as :meth:`__del__` is not always reliable.
1947 raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
1950 nbt
._bt
_ctf
_stream
_put
(self
._s
)
1953 def discarded_events(self
):
1955 Number of discarded (lost) events in this stream so far.
1957 :exc:`ValueError` is raised on error.
1960 ret
, count
= nbt
._bt
_ctf
_stream
_get
_discarded
_events
_count
(self
._s
)
1963 raise ValueError("Could not get the stream discarded events count")
1967 def append_discarded_events(self
, event_count
):
1969 Appends *event_count* discarded events to this stream.
1972 nbt
._bt
_ctf
_stream
_append
_discarded
_events
(self
._s
, event_count
)
1974 def append_event(self
, event
):
1976 Appends event *event* (:class:`Event` object) to this stream.
1978 The stream's associated clock will be sampled during this call.
1979 *event* **shall not** be modified after being appended to this
1982 :exc:`ValueError` is raised on error.
1985 ret
= nbt
._bt
_ctf
_stream
_append
_event
(self
._s
, event
._e
)
1988 raise ValueError("Could not append event to stream.")
1991 def packet_context(self
):
1993 Stream packet context field (instance of
1994 :class:`StructureField`).
1996 Set this attribute to assign a stream packet context field
1999 :exc:`ValueError` is raised on error.
2002 native_field
= nbt
._bt
_ctf
_stream
_get
_packet
_context
(self
._s
)
2004 if native_field
is None:
2005 raise ValueError("Invalid Stream.")
2007 return Field
._create
_field
_from
_native
_instance
(native_field
)
2009 @packet_context.setter
2010 def packet_context(self
, field
):
2011 if not isinstance(field
, StructureField
):
2012 raise TypeError("Argument field must be of type StructureField")
2014 ret
= nbt
._bt
_ctf
_stream
_set
_packet
_context
(self
._s
, field
._f
)
2017 raise ValueError("Invalid packet context field.")
2021 Flushes the current packet of this stream to disk. Events
2022 subsequently appended to the stream will be added to a new
2025 :exc:`ValueError` is raised on error.
2028 ret
= nbt
._bt
_ctf
_stream
_flush
(self
._s
)
2031 raise ValueError("Could not flush stream.")
2036 This object is the CTF writer API context. It oversees its streams
2037 and clocks, and is responsible for writing one CTF trace.
2040 def __init__(self
, path
):
2042 Creates a CTF writer, initializing a new CTF trace at path
2045 *path* must be an existing directory, since a CTF trace is
2046 made of multiple files.
2048 :exc:`ValueError` is raised if the creation fails.
2051 self
._w
= nbt
._bt
_ctf
_writer
_create
(path
)
2054 raise ValueError("Writer creation failed.")
2057 nbt
._bt
_ctf
_writer
_put
(self
._w
)
2059 def create_stream(self
, stream_class
):
2061 Creates and registers a new stream based on stream class
2064 This is the standard way of creating a :class:`Stream` object:
2065 the user is not allowed to instantiate this class.
2067 Returns a new :class:`Stream` object.
2070 if not isinstance(stream_class
, StreamClass
):
2071 raise TypeError("Invalid stream_class type.")
2073 stream
= Stream
.__new
__(Stream
)
2074 stream
._s
= nbt
._bt
_ctf
_writer
_create
_stream
(self
._w
, stream_class
._sc
)
2078 def add_environment_field(self
, name
, value
):
2080 Sets the CTF environment variable named *name* to value *value*
2081 (converted to a string).
2083 :exc:`ValueError` is raised on error.
2086 ret
= nbt
._bt
_ctf
_writer
_add
_environment
_field
(self
._w
, str(name
),
2090 raise ValueError("Could not add environment field to trace.")
2092 def add_clock(self
, clock
):
2094 Registers :class:`Clock` object *clock* to the writer.
2096 You *must* register CTF clocks assigned to stream classes
2099 :exc:`ValueError` is raised if the creation fails.
2102 ret
= nbt
._bt
_ctf
_writer
_add
_clock
(self
._w
, clock
._c
)
2105 raise ValueError("Could not add clock to Writer.")
2110 Current metadata of this trace (:class:`str`).
2113 return nbt
._bt
_ctf
_writer
_get
_metadata
_string
(self
._w
)
2115 def flush_metadata(self
):
2117 Flushes the trace's metadata to the metadata file.
2120 nbt
._bt
_ctf
_writer
_flush
_metadata
(self
._w
)
2123 def byte_order(self
):
2125 Native byte order of this trace (one of
2126 :class:`babeltrace.common.ByteOrder` constants).
2128 This is the actual byte order that is used when a field
2130 :attr:`babeltrace.common.ByteOrder.BYTE_ORDER_NATIVE`
2133 Set this attribute to change the trace's native byte order.
2135 Defaults to the host machine's endianness.
2137 :exc:`ValueError` is raised on error.
2140 raise NotImplementedError("Getter not implemented.")
2143 def byte_order(self
, byte_order
):
2144 ret
= nbt
._bt
_ctf
_writer
_set
_byte
_order
(self
._w
, byte_order
)
2147 raise ValueError("Could not set trace byte order.")