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 def offset_seconds(self
):
164 Clock offset in seconds since POSIX.1 Epoch (integer).
166 Set this attribute to change the clock's offset in seconds.
168 :exc:`ValueError` is raised on error.
171 ret
, offset_s
= nbt
._bt
_ctf
_clock
_get
_offset
_s
(self
._c
)
174 raise ValueError("Invalid clock instance")
178 @offset_seconds.setter
179 def offset_seconds(self
, offset_s
):
180 ret
= nbt
._bt
_ctf
_clock
_set
_offset
_s
(self
._c
, offset_s
)
183 raise ValueError("Invalid offset value.")
188 Clock offset in ticks since (POSIX.1 Epoch +
189 :attr:`offset_seconds`).
191 Set this attribute to change the clock's offset.
193 :exc:`ValueError` is raised on error.
196 ret
, offset
= nbt
._bt
_ctf
_clock
_get
_offset
(self
._c
)
199 raise ValueError("Invalid clock instance")
204 def offset(self
, offset
):
205 ret
= nbt
._bt
_ctf
_clock
_set
_offset
(self
._c
, offset
)
208 raise ValueError("Invalid offset value.")
213 ``True`` if this clock is absolute, i.e. if the clock is a
214 global reference across the other clocks of the trace.
216 Set this attribute to change the clock's absolute state
219 :exc:`ValueError` is raised on error.
222 is_absolute
= nbt
._bt
_ctf
_clock
_get
_is
_absolute
(self
._c
)
224 if is_absolute
== -1:
225 raise ValueError("Invalid clock instance")
227 return False if is_absolute
== 0 else True
230 def absolute(self
, is_absolute
):
231 ret
= nbt
._bt
_ctf
_clock
_set
_is
_absolute
(self
._c
, int(is_absolute
))
234 raise ValueError("Could not set the clock absolute attribute.")
239 Clock UUID (an :class:`uuid.UUID` object).
241 Set this attribute to change the clock's UUID.
243 :exc:`ValueError` is raised on error.
249 ret
, value
= nbt
._bt
_python
_ctf
_clock
_get
_uuid
_index
(self
._c
, i
)
252 raise ValueError("Invalid clock instance")
254 uuid_list
.append(value
)
256 return UUID(bytes
=bytes(uuid_list
))
259 def uuid(self
, uuid
):
260 uuid_bytes
= uuid
.bytes
262 if len(uuid_bytes
) != 16:
263 raise ValueError("Invalid UUID provided. UUID length must be 16 bytes")
265 for i
in range(len(uuid_bytes
)):
266 ret
= nbt
._bt
_python
_ctf
_clock
_set
_uuid
_index
(self
._c
, i
,
270 raise ValueError("Invalid clock instance")
275 Clock current time; nanoseconds (integer) since clock origin
276 (POSIX.1 Epoch + :attr:`offset_seconds` + :attr:`offset`).
278 Set this attribute to change the clock's current time.
280 :exc:`ValueError` is raised on error.
283 ret
, time
= nbt
._bt
_ctf
_clock
_get
_time
(self
._c
)
286 raise ValueError("Invalid clock instance")
291 def time(self
, time
):
292 ret
= nbt
._bt
_ctf
_clock
_set
_time
(self
._c
, time
)
295 raise ValueError("Invalid time value.")
300 Display base of an integer.
318 # keep this for backward compatibility
319 INTEGER_BASE_UNKNOWN
= -1
320 INTEGER_BASE_BINARY
= 2
321 INTEGER_BASE_OCTAL
= 8
322 INTEGER_BASE_DECIMAL
= 10
323 INTEGER_BASE_HEXADECIMAL
= 16
326 class FieldDeclaration
:
328 Base class of all field declarations. This class is not meant to
329 be instantiated by the user; use one of the concrete field
330 declaration subclasses instead.
333 class IntegerBase(IntegerBase
):
338 raise ValueError("FieldDeclaration creation failed.")
341 nbt
._bt
_ctf
_field
_type
_put
(self
._ft
)
344 def _create_field_declaration_from_native_instance(
345 native_field_declaration
):
347 common
.CTFTypeId
.INTEGER
: IntegerFieldDeclaration
,
348 common
.CTFTypeId
.FLOAT
: FloatFieldDeclaration
,
349 common
.CTFTypeId
.ENUM
: EnumerationFieldDeclaration
,
350 common
.CTFTypeId
.STRING
: StringFieldDeclaration
,
351 common
.CTFTypeId
.STRUCT
: StructureFieldDeclaration
,
352 common
.CTFTypeId
.VARIANT
: VariantFieldDeclaration
,
353 common
.CTFTypeId
.ARRAY
: ArrayFieldDeclaration
,
354 common
.CTFTypeId
.SEQUENCE
: SequenceFieldDeclaration
357 field_type_id
= nbt
._bt
_ctf
_field
_type
_get
_type
_id
(native_field_declaration
)
359 if field_type_id
== common
.CTFTypeId
.UNKNOWN
:
360 raise TypeError("Invalid field instance")
362 declaration
= Field
.__new
__(Field
)
363 declaration
._ft
= native_field_declaration
364 declaration
.__class
__ = type_dict
[field_type_id
]
371 Field alignment in bits (integer).
373 Set this attribute to change this field's alignment.
375 :exc:`ValueError` is raised on error.
378 return nbt
._bt
_ctf
_field
_type
_get
_alignment
(self
._ft
)
381 def alignment(self
, alignment
):
382 ret
= nbt
._bt
_ctf
_field
_type
_set
_alignment
(self
._ft
, alignment
)
385 raise ValueError("Invalid alignment value.")
388 def byte_order(self
):
390 Field byte order (one of :class:`babeltrace.common.ByteOrder`
393 Set this attribute to change this field's byte order.
395 :exc:`ValueError` is raised on error.
398 return nbt
._bt
_ctf
_field
_type
_get
_byte
_order
(self
._ft
)
401 def byte_order(self
, byte_order
):
402 ret
= nbt
._bt
_ctf
_field
_type
_set
_byte
_order
(self
._ft
, byte_order
)
405 raise ValueError("Could not set byte order value.")
408 class IntegerFieldDeclaration(FieldDeclaration
):
410 Integer field declaration.
413 def __init__(self
, size
):
415 Creates an integer field declaration of size *size* bits.
417 :exc:`ValueError` is raised on error.
420 self
._ft
= nbt
._bt
_ctf
_field
_type
_integer
_create
(size
)
426 Integer size in bits (integer).
428 Set this attribute to change this integer's size.
430 :exc:`ValueError` is raised on error.
433 ret
= nbt
._bt
_ctf
_field
_type
_integer
_get
_size
(self
._ft
)
436 raise ValueError("Could not get Integer size attribute.")
443 ``True`` if this integer is signed.
445 Set this attribute to change this integer's signedness
448 :exc:`ValueError` is raised on error.
451 ret
= nbt
._bt
_ctf
_field
_type
_integer
_get
_signed
(self
._ft
)
454 raise ValueError("Could not get Integer signed attribute.")
461 def signed(self
, signed
):
462 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_signed
(self
._ft
, signed
)
465 raise ValueError("Could not set Integer signed attribute.")
470 Integer display base (one of :class:`IntegerBase` constants).
472 Set this attribute to change this integer's display base.
474 :exc:`ValueError` is raised on error.
477 return nbt
._bt
_ctf
_field
_type
_integer
_get
_base
(self
._ft
)
480 def base(self
, base
):
481 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_base
(self
._ft
, base
)
484 raise ValueError("Could not set Integer base.")
489 Integer encoding (one of
490 :class:`babeltrace.common.CTFStringEncoding` constants).
492 Set this attribute to change this integer's encoding.
494 :exc:`ValueError` is raised on error.
497 return nbt
._bt
_ctf
_field
_type
_integer
_get
_encoding
(self
._ft
)
500 def encoding(self
, encoding
):
501 ret
= nbt
._bt
_ctf
_field
_type
_integer
_set
_encoding
(self
._ft
, encoding
)
504 raise ValueError("Could not set Integer encoding.")
507 class EnumerationFieldDeclaration(FieldDeclaration
):
509 Enumeration field declaration. A CTF enumeration maps labels to
513 def __init__(self
, integer_type
):
515 Creates an enumeration field declaration, with *integer_type*
516 being the underlying :class:`IntegerFieldDeclaration` for storing
519 :exc:`ValueError` is raised on error.
522 isinst
= isinstance(integer_type
, IntegerFieldDeclaration
)
524 if integer_type
is None or not isinst
:
525 raise TypeError("Invalid integer container.")
527 self
._ft
= nbt
._bt
_ctf
_field
_type
_enumeration
_create
(integer_type
._ft
)
533 Underlying container (:class:`IntegerFieldDeclaration`).
535 :exc:`TypeError` is raised on error.
538 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_container
_type
(self
._ft
)
541 raise TypeError("Invalid enumeration declaration")
543 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
545 def add_mapping(self
, name
, range_start
, range_end
):
547 Adds a mapping to the enumeration field declaration, from the
548 label named *name* to range [*range_start*, *range_end*], where
549 *range_start* and *range_end* are integers included in the
552 :exc:`ValueError` is raised on error.
555 if range_start
< 0 or range_end
< 0:
556 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_add
_mapping
(self
._ft
,
561 ret
= nbt
._bt
_ctf
_field
_type
_enumeration
_add
_mapping
_unsigned
(self
._ft
,
567 raise ValueError("Could not add mapping to enumeration declaration.")
572 Generates the mappings of this enumeration field declaration
573 (:class:`EnumerationMapping` objects).
575 :exc:`TypeError` is raised on error.
578 signed
= self
.container
.signed
580 count
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_count
(self
._ft
)
582 for i
in range(count
):
584 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, i
)
586 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, i
)
589 msg
= "Could not get Enumeration mapping at index {}".format(i
)
592 name
, range_start
, range_end
= ret
593 yield EnumerationMapping(name
, range_start
, range_end
)
595 def get_mapping_by_name(self
, name
):
597 Returns the :class:`EnumerationMapping` object for the label
600 :exc:`TypeError` is raised on error.
603 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_name
(self
._ft
, name
)
608 if self
.container
.signed
:
609 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, index
)
611 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, index
)
614 msg
= "Could not get Enumeration mapping at index {}".format(i
)
617 name
, range_start
, range_end
= ret
619 return EnumerationMapping(name
, range_start
, range_end
)
621 def get_mapping_by_value(self
, value
):
623 Returns the :class:`EnumerationMapping` object for the value
626 :exc:`TypeError` is raised on error.
630 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_value
(self
._ft
, value
)
632 index
= nbt
._bt
_ctf
_field
_type
_enumeration
_get
_mapping
_index
_by
_unsigned
_value
(self
._ft
, value
)
637 if self
.container
.signed
:
638 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
(self
._ft
, index
)
640 ret
= nbt
._bt
_python
_ctf
_field
_type
_enumeration
_get
_mapping
_unsigned
(self
._ft
, index
)
643 msg
= "Could not get Enumeration mapping at index {}".format(i
)
646 name
, range_start
, range_end
= ret
648 return EnumerationMapping(name
, range_start
, range_end
)
651 class FloatingPointFieldDeclaration(FieldDeclaration
):
653 Floating point number field declaration.
655 A CTF floating point number is a made of three sections: the sign
656 bit, the exponent bits, and the mantissa bits. The most significant
657 bit of the resulting binary word is the sign bit, and is included
658 in the number of mantissa bits.
661 `IEEE 754 <http://en.wikipedia.org/wiki/IEEE_floating_point>`_
662 single precision floating point number is represented on a 32-bit
663 word using an 8-bit exponent (``e``) and a 24-bit mantissa (``m``),
664 the latter count including the sign bit (``s``)::
666 s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm
668 The IEEE 754 double precision floating point number uses an
669 11-bit exponent and a 53-bit mantissa.
672 #: IEEE 754 single precision floating point number exponent size
675 #: IEEE 754 double precision floating point number exponent size
678 #: IEEE 754 single precision floating point number mantissa size
681 #: IEEE 754 double precision floating point number mantissa size
686 Creates a floating point number field declaration.
688 :exc:`ValueError` is raised on error.
691 self
._ft
= nbt
._bt
_ctf
_field
_type
_floating
_point
_create
()
695 def exponent_digits(self
):
697 Floating point number exponent section size in bits (integer).
699 Set this attribute to change the floating point number's
700 exponent section's size. You may use :attr:`FLT_EXP_DIG` or
701 :attr:`DBL_EXP_DIG` for IEEE 754 floating point numbers.
703 :exc:`ValueError` is raised on error.
706 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_get
_exponent
_digits
(self
._ft
)
710 "Could not get Floating point exponent digit count")
714 @exponent_digits.setter
715 def exponent_digits(self
, exponent_digits
):
716 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_set
_exponent
_digits
(self
._ft
,
720 raise ValueError("Could not set exponent digit count.")
723 def mantissa_digits(self
):
725 Floating point number mantissa section size in bits (integer).
727 Set this attribute to change the floating point number's
728 mantissa section's size. You may use :attr:`FLT_MANT_DIG` or
729 :attr:`DBL_MANT_DIG` for IEEE 754 floating point numbers.
731 :exc:`ValueError` is raised on error.
734 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_get
_mantissa
_digits
(self
._ft
)
737 raise TypeError("Could not get Floating point mantissa digit count")
741 @mantissa_digits.setter
742 def mantissa_digits(self
, mantissa_digits
):
743 ret
= nbt
._bt
_ctf
_field
_type
_floating
_point
_set
_mantissa
_digits
(self
._ft
,
747 raise ValueError("Could not set mantissa digit count.")
750 class FloatFieldDeclaration(FloatingPointFieldDeclaration
):
754 class StructureFieldDeclaration(FieldDeclaration
):
756 Structure field declaration, i.e. an ordered mapping from field
757 names to field declarations.
762 Creates an empty structure field declaration.
764 :exc:`ValueError` is raised on error.
767 self
._ft
= nbt
._bt
_ctf
_field
_type
_structure
_create
()
770 def add_field(self
, field_type
, field_name
):
772 Appends one :class:`FieldDeclaration` *field_type* named
773 *field_name* to the structure's ordered map.
775 :exc:`ValueError` is raised on error.
778 ret
= nbt
._bt
_ctf
_field
_type
_structure
_add
_field
(self
._ft
,
783 raise ValueError("Could not add field to structure.")
788 Generates the (field name, :class:`FieldDeclaration`) pairs
791 :exc:`TypeError` is raised on error.
794 count
= nbt
._bt
_ctf
_field
_type
_structure
_get
_field
_count
(self
._ft
)
797 raise TypeError("Could not get Structure field count")
799 for i
in range(count
):
800 field_name
= nbt
._bt
_python
_ctf
_field
_type
_structure
_get
_field
_name
(self
._ft
, i
)
802 if field_name
is None:
803 msg
= "Could not get Structure field name at index {}".format(i
)
806 field_type_native
= nbt
._bt
_python
_ctf
_field
_type
_structure
_get
_field
_type
(self
._ft
, i
)
808 if field_type_native
is None:
809 msg
= "Could not get Structure field type at index {}".format(i
)
812 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
813 yield (field_name
, field_type
)
815 def get_field_by_name(self
, name
):
817 Returns the :class:`FieldDeclaration` mapped to the field name
818 *name* in this structure.
820 :exc:`TypeError` is raised on error.
823 field_type_native
= nbt
._bt
_ctf
_field
_type
_structure
_get
_field
_type
_by
_name
(self
._ft
, name
)
825 if field_type_native
is None:
826 msg
= "Could not find Structure field with name {}".format(name
)
829 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
832 class VariantFieldDeclaration(FieldDeclaration
):
834 Variant field declaration.
836 A CTF variant is a dynamic selection between different fields.
837 The value of a *tag* (a CTF enumeration) determines what is the
838 current selected field. All the possible fields must be added to
839 its field declaration before using an actual variant field.
842 def __init__(self
, enum_tag
, tag_name
):
844 Creates an empty variant field declaration with tag field
845 declaration *enum_tag* (instance of
846 :class:`EnumerationFieldDeclaration`) named *tag_name*
849 :exc:`ValueError` is raised on error.
852 isinst
= isinstance(enum_tag
, EnumerationFieldDeclaration
)
853 if enum_tag
is None or not isinst
:
854 raise TypeError("Invalid tag type; must be of type EnumerationFieldDeclaration.")
856 self
._ft
= nbt
._bt
_ctf
_field
_type
_variant
_create
(enum_tag
._ft
,
863 Variant field declaration tag name.
865 :exc:`TypeError` is raised on error.
868 ret
= nbt
._bt
_ctf
_field
_type
_variant
_get
_tag
_name
(self
._ft
)
871 raise TypeError("Could not get Variant tag name")
878 Variant field declaration tag field declaration
879 (:class:`EnumerationFieldDeclaration` object).
881 :exc:`TypeError` is raised on error.
884 ret
= nbt
._bt
_ctf
_field
_type
_variant
_get
_tag
_type
(self
._ft
)
887 raise TypeError("Could not get Variant tag type")
889 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
891 def add_field(self
, field_type
, field_name
):
893 Registers the :class:`FieldDeclaration` object *field_type*
894 as the variant's selected type when the variant's tag's current
895 label is *field_name*.
897 :exc:`ValueError` is raised on error.
900 ret
= nbt
._bt
_ctf
_field
_type
_variant
_add
_field
(self
._ft
,
905 raise ValueError("Could not add field to variant.")
910 Generates the (field name, :class:`FieldDeclaration`) pairs
911 of this variant field declaration.
913 :exc:`TypeError` is raised on error.
916 count
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_count
(self
._ft
)
919 raise TypeError("Could not get Variant field count")
921 for i
in range(count
):
922 field_name
= nbt
._bt
_python
_ctf
_field
_type
_variant
_get
_field
_name
(self
._ft
, i
)
924 if field_name
is None:
925 msg
= "Could not get Variant field name at index {}".format(i
)
928 field_type_native
= nbt
._bt
_python
_ctf
_field
_type
_variant
_get
_field
_type
(self
._ft
, i
)
930 if field_type_native
is None:
931 msg
= "Could not get Variant field type at index {}".format(i
)
934 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
935 yield (field_name
, field_type
)
937 def get_field_by_name(self
, name
):
939 Returns the :class:`FieldDeclaration` selected when the
940 variant's tag's current label is *name*.
942 :exc:`TypeError` is raised on error.
945 field_type_native
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_type
_by
_name
(self
._ft
,
948 if field_type_native
is None:
949 msg
= "Could not find Variant field with name {}".format(name
)
952 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
954 def get_field_from_tag(self
, tag
):
956 Returns the :class:`FieldDeclaration` selected by the current
957 label of the :class:`EnumerationField` *tag*.
959 :exc:`TypeError` is raised on error.
962 field_type_native
= nbt
._bt
_ctf
_field
_type
_variant
_get
_field
_type
_from
_tag
(self
._ft
, tag
._f
)
964 if field_type_native
is None:
965 msg
= "Could not find Variant field with tag value {}".format(tag
.value
)
968 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
971 class ArrayFieldDeclaration(FieldDeclaration
):
973 Static array field declaration.
976 def __init__(self
, element_type
, length
):
978 Creates a static array field declaration of *length*
979 elements of type *element_type* (:class:`FieldDeclaration`).
981 :exc:`ValueError` is raised on error.
984 self
._ft
= nbt
._bt
_ctf
_field
_type
_array
_create
(element_type
._ft
,
989 def element_type(self
):
991 Type of the elements of this this static array (subclass of
992 :class:`FieldDeclaration`).
994 :exc:`TypeError` is raised on error.
997 ret
= nbt
._bt
_ctf
_field
_type
_array
_get
_element
_type
(self
._ft
)
1000 raise TypeError("Could not get Array element type")
1002 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
1007 Length of this static array (integer).
1009 :exc:`TypeError` is raised on error.
1012 ret
= nbt
._bt
_ctf
_field
_type
_array
_get
_length
(self
._ft
)
1015 raise TypeError("Could not get Array length")
1020 class SequenceFieldDeclaration(FieldDeclaration
):
1022 Sequence (dynamic array) field declaration.
1025 def __init__(self
, element_type
, length_field_name
):
1027 Creates a sequence field declaration of
1028 elements of type *element_type* (:class:`FieldDeclaration`).
1029 The length of a sequence field based on this sequence field
1030 declaration is obtained by retrieving the dynamic integer
1031 value of the field named *length_field_name*.
1033 :exc:`ValueError` is raised on error.
1036 self
._ft
= nbt
._bt
_ctf
_field
_type
_sequence
_create
(element_type
._ft
,
1037 str(length_field_name
))
1041 def element_type(self
):
1043 Type of the elements of this sequence (subclass of
1044 :class:`FieldDeclaration`).
1046 :exc:`TypeError` is raised on error.
1049 ret
= nbt
._bt
_ctf
_field
_type
_sequence
_get
_element
_type
(self
._ft
)
1052 raise TypeError("Could not get Sequence element type")
1054 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(ret
)
1057 def length_field_name(self
):
1059 Name of the integer field defining the dynamic length of
1060 sequence fields based on this sequence field declaration.
1062 :exc:`TypeError` is raised on error.
1065 ret
= nbt
._bt
_ctf
_field
_type
_sequence
_get
_length
_field
_name
(self
._ft
)
1068 raise TypeError("Could not get Sequence length field name")
1073 class StringFieldDeclaration(FieldDeclaration
):
1075 String (NULL-terminated array of bytes) field declaration.
1080 Creates a string field declaration.
1082 :exc:`ValueError` is raised on error.
1085 self
._ft
= nbt
._bt
_ctf
_field
_type
_string
_create
()
1091 String encoding (one of
1092 :class:`babeltrace.common.CTFStringEncoding` constants).
1094 Set this attribute to change this string's encoding.
1096 :exc:`ValueError` is raised on error.
1099 return nbt
._bt
_ctf
_field
_type
_string
_get
_encoding
(self
._ft
)
1102 def encoding(self
, encoding
):
1103 ret
= nbt
._bt
_ctf
_field
_type
_string
_set
_encoding
(self
._ft
, encoding
)
1105 raise ValueError("Could not set string encoding.")
1109 def create_field(field_type
):
1111 Create an instance of a field.
1113 isinst
= isinstance(field_type
, FieldDeclaration
)
1115 if field_type
is None or not isinst
:
1116 raise TypeError("Invalid field_type. Type must be a FieldDeclaration-derived class.")
1118 if isinstance(field_type
, IntegerFieldDeclaration
):
1119 return IntegerField(field_type
)
1120 elif isinstance(field_type
, EnumerationFieldDeclaration
):
1121 return EnumerationField(field_type
)
1122 elif isinstance(field_type
, FloatFieldDeclaration
):
1123 return FloatingPointField(field_type
)
1124 elif isinstance(field_type
, StructureFieldDeclaration
):
1125 return StructureField(field_type
)
1126 elif isinstance(field_type
, VariantFieldDeclaration
):
1127 return VariantField(field_type
)
1128 elif isinstance(field_type
, ArrayFieldDeclaration
):
1129 return ArrayField(field_type
)
1130 elif isinstance(field_type
, SequenceFieldDeclaration
):
1131 return SequenceField(field_type
)
1132 elif isinstance(field_type
, StringFieldDeclaration
):
1133 return StringField(field_type
)
1138 Base class of all fields. This class is not meant to be
1139 instantiated by the user, and neither are its subclasses. Use
1140 :meth:`Event.payload` to access specific, concrete fields of
1144 def __init__(self
, field_type
):
1145 if not isinstance(field_type
, FieldDeclaration
):
1146 raise TypeError("Invalid field_type argument.")
1148 self
._f
= nbt
._bt
_ctf
_field
_create
(field_type
._ft
)
1151 raise ValueError("Field creation failed.")
1154 nbt
._bt
_ctf
_field
_put
(self
._f
)
1157 def _create_field_from_native_instance(native_field_instance
):
1159 common
.CTFTypeId
.INTEGER
: IntegerField
,
1160 common
.CTFTypeId
.FLOAT
: FloatingPointField
,
1161 common
.CTFTypeId
.ENUM
: EnumerationField
,
1162 common
.CTFTypeId
.STRING
: StringField
,
1163 common
.CTFTypeId
.STRUCT
: StructureField
,
1164 common
.CTFTypeId
.VARIANT
: VariantField
,
1165 common
.CTFTypeId
.ARRAY
: ArrayField
,
1166 common
.CTFTypeId
.SEQUENCE
: SequenceField
1169 field_type
= nbt
._bt
_python
_get
_field
_type
(native_field_instance
)
1171 if field_type
== common
.CTFTypeId
.UNKNOWN
:
1172 raise TypeError("Invalid field instance")
1174 field
= Field
.__new
__(Field
)
1175 field
._f
= native_field_instance
1176 field
.__class
__ = type_dict
[field_type
]
1181 def declaration(self
):
1183 Field declaration (subclass of :class:`FieldDeclaration`).
1185 :exc:`TypeError` is raised on error.
1188 native_field_type
= nbt
._bt
_ctf
_field
_get
_type
(self
._f
)
1190 if native_field_type
is None:
1191 raise TypeError("Invalid field instance")
1192 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(
1196 class IntegerField(Field
):
1198 Integer field, based on an :class:`IntegerFieldDeclaration` object.
1204 Integer value (:class:`int`).
1206 Set this attribute to change the integer field's value.
1208 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1211 signedness
= nbt
._bt
_python
_field
_integer
_get
_signedness
(self
._f
)
1214 raise TypeError("Invalid integer instance.")
1217 ret
, value
= nbt
._bt
_ctf
_field
_unsigned
_integer
_get
_value
(self
._f
)
1219 ret
, value
= nbt
._bt
_ctf
_field
_signed
_integer
_get
_value
(self
._f
)
1222 raise ValueError("Could not get integer field value.")
1227 def value(self
, value
):
1228 if not isinstance(value
, int):
1229 raise TypeError("IntegerField's value must be an int")
1231 signedness
= nbt
._bt
_python
_field
_integer
_get
_signedness
(self
._f
)
1233 raise TypeError("Invalid integer instance.")
1236 ret
= nbt
._bt
_ctf
_field
_unsigned
_integer
_set
_value
(self
._f
, value
)
1238 ret
= nbt
._bt
_ctf
_field
_signed
_integer
_set
_value
(self
._f
, value
)
1241 raise ValueError("Could not set integer field value.")
1244 class EnumerationField(Field
):
1246 Enumeration field, based on an
1247 :class:`EnumerationFieldDeclaration` object.
1251 def container(self
):
1253 Underlying container (:class:`IntegerField`).
1255 :exc:`TypeError` is raised on error.
1258 container
= IntegerField
.__new
__(IntegerField
)
1259 container
._f
= nbt
._bt
_ctf
_field
_enumeration
_get
_container
(self
._f
)
1261 if container
._f
is None:
1262 raise TypeError("Invalid enumeration field type.")
1269 Current label of this enumeration field (:class:`str`).
1271 Set this attribute to an integer (:class:`int`) to change the
1272 enumeration field's value.
1274 :exc:`ValueError` is raised on error.
1277 value
= nbt
._bt
_ctf
_field
_enumeration
_get
_mapping
_name
(self
._f
)
1280 raise ValueError("Could not get enumeration mapping name.")
1285 def value(self
, value
):
1286 if not isinstance(value
, int):
1287 raise TypeError("EnumerationField value must be an int")
1289 self
.container
.value
= value
1292 class FloatingPointField(Field
):
1294 Floating point number field, based on a
1295 :class:`FloatingPointFieldDeclaration` object.
1301 Floating point number value (:class:`float`).
1303 Set this attribute to change the floating point number field's
1306 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1309 ret
, value
= nbt
._bt
_ctf
_field
_floating
_point
_get
_value
(self
._f
)
1312 raise ValueError("Could not get floating point field value.")
1317 def value(self
, value
):
1318 if not isinstance(value
, int) and not isinstance(value
, float):
1319 raise TypeError("Value must be either a float or an int")
1321 ret
= nbt
._bt
_ctf
_field
_floating
_point
_set
_value
(self
._f
, float(value
))
1324 raise ValueError("Could not set floating point field value.")
1327 # oops!! This class is provided to ensure backward-compatibility since
1328 # a stable release publicly exposed this abomination.
1329 class FloatFieldingPoint(FloatingPointField
):
1333 class StructureField(Field
):
1335 Structure field, based on a
1336 :class:`StructureFieldDeclaration` object.
1339 def field(self
, field_name
):
1341 Returns the structure :class:`Field` named *field_name*.
1343 :exc:`ValueError` is raised on error.
1346 native_instance
= nbt
._bt
_ctf
_field
_structure
_get
_field
(self
._f
,
1349 if native_instance
is None:
1350 raise ValueError("Invalid field_name provided.")
1352 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1355 class VariantField(Field
):
1357 Variant field, based on a
1358 :class:`VariantFieldDeclaration` object.
1361 def field(self
, tag
):
1363 Returns the :class:`Field` selected by the current label of
1364 *tag* (:class:`EnumerationField`).
1366 :exc:`ValueError` is raised on error.
1369 native_instance
= nbt
._bt
_ctf
_field
_variant
_get
_field
(self
._f
, tag
._f
)
1371 if native_instance
is None:
1372 raise ValueError("Invalid tag provided.")
1374 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1377 class ArrayField(Field
):
1379 Static array field, based on an
1380 :class:`ArrayFieldDeclaration` object.
1383 def field(self
, index
):
1385 Returns the :class:`Field` at index *index* in this static
1388 :exc:`IndexError` is raised on error.
1391 native_instance
= nbt
._bt
_ctf
_field
_array
_get
_field
(self
._f
, index
)
1393 if native_instance
is None:
1394 raise IndexError("Invalid index provided.")
1396 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1399 class SequenceField(Field
):
1401 Sequence (dynamic array) field, based on a
1402 :class:`SequenceFieldDeclaration` object.
1408 Sequence length (:class:`IntegerField`).
1410 Set this attribute to change the sequence length's integer
1411 field (integer must be unsigned).
1413 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1416 native_instance
= nbt
._bt
_ctf
_field
_sequence
_get
_length
(self
._f
)
1418 if native_instance
is None:
1421 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1424 def length(self
, length_field
):
1425 if not isinstance(length_field
, IntegerField
):
1426 raise TypeError("Invalid length field.")
1428 if length_field
.declaration
.signed
:
1429 raise TypeError("Sequence field length must be unsigned")
1431 ret
= nbt
._bt
_ctf
_field
_sequence
_set
_length
(self
._f
, length_field
._f
)
1434 raise ValueError("Could not set sequence length.")
1436 def field(self
, index
):
1438 Returns the :class:`Field` at index *index* in this sequence.
1440 :exc:`ValueError` is raised on error.
1443 native_instance
= nbt
._bt
_ctf
_field
_sequence
_get
_field
(self
._f
, index
)
1445 if native_instance
is None:
1446 raise ValueError("Could not get sequence element at index.")
1448 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1451 class StringField(Field
):
1453 String (NULL-terminated array of bytes) field.
1459 String value (:class:`str`).
1461 Set this attribute to change the string's value.
1463 :exc:`ValueError` or :exc:`TypeError` are raised on error.
1466 return nbt
._bt
_ctf
_field
_string
_get
_value
(self
._f
)
1469 def value(self
, value
):
1470 ret
= nbt
._bt
_ctf
_field
_string
_set
_value
(self
._f
, str(value
))
1473 raise ValueError("Could not set string field value.")
1478 An event class contains the properties of specific
1479 events (:class:`Event`). Any concrete event must be linked with an
1480 :class:`EventClass`.
1482 Some attributes are automatically set when creating an event class.
1483 For example, if no numeric ID is explicitly set using the
1484 :attr:`id` attribute, a default, unique ID within the stream class
1485 containing this event class will be created when needed.
1488 def __init__(self
, name
):
1490 Creates an event class named *name*.
1492 :exc:`ValueError` is raised on error.
1495 self
._ec
= nbt
._bt
_ctf
_event
_class
_create
(name
)
1497 if self
._ec
is None:
1498 raise ValueError("Event class creation failed.")
1501 nbt
._bt
_ctf
_event
_class
_put
(self
._ec
)
1503 def add_field(self
, field_type
, field_name
):
1505 Adds a field declaration *field_type* named *field_name* to
1508 *field_type* must be one of:
1510 * :class:`IntegerFieldDeclaration`
1511 * :class:`FloatingPointFieldDeclaration`
1512 * :class:`EnumerationFieldDeclaration`
1513 * :class:`StringFieldDeclaration`
1514 * :class:`ArrayFieldDeclaration`
1515 * :class:`SequenceFieldDeclaration`
1516 * :class:`StructureFieldDeclaration`
1517 * :class:`VariantFieldDeclaration`
1519 :exc:`ValueError` is raised on error.
1522 ret
= nbt
._bt
_ctf
_event
_class
_add
_field
(self
._ec
, field_type
._ft
,
1526 raise ValueError("Could not add field to event class.")
1534 name
= nbt
._bt
_ctf
_event
_class
_get
_name
(self
._ec
)
1537 raise TypeError("Could not get EventClass name")
1544 Event class' numeric ID.
1546 Set this attribute to assign a numeric ID to this event class.
1547 This ID must be unique amongst all the event class IDs of a
1550 :exc:`TypeError` is raised on error.
1553 id = nbt
._bt
_ctf
_event
_class
_get
_id
(self
._ec
)
1556 raise TypeError("Could not get EventClass id")
1562 ret
= nbt
._bt
_ctf
_event
_class
_set
_id
(self
._ec
, id)
1565 raise TypeError("Can't change an Event Class id after it has been assigned to a stream class")
1568 def stream_class(self
):
1570 :class:`StreamClass` object containing this event class,
1571 or ``None`` if not set.
1574 stream_class_native
= nbt
._bt
_ctf
_event
_class
_get
_stream
_class
(self
._ec
)
1576 if stream_class_native
is None:
1579 stream_class
= StreamClass
.__new
__(StreamClass
)
1580 stream_class
._sc
= stream_class_native
1587 Generates the (field name, :class:`FieldDeclaration`) pairs of
1590 :exc:`TypeError` is raised on error.
1593 count
= nbt
._bt
_ctf
_event
_class
_get
_field
_count
(self
._ec
)
1596 raise TypeError("Could not get EventClass' field count")
1598 for i
in range(count
):
1599 field_name
= nbt
._bt
_python
_ctf
_event
_class
_get
_field
_name
(self
._ec
, i
)
1601 if field_name
is None:
1602 msg
= "Could not get EventClass' field name at index {}".format(i
)
1603 raise TypeError(msg
)
1605 field_type_native
= nbt
._bt
_python
_ctf
_event
_class
_get
_field
_type
(self
._ec
, i
)
1607 if field_type_native
is None:
1608 msg
= "Could not get EventClass' field type at index {}".format(i
)
1609 raise TypeError(msg
)
1611 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1612 yield (field_name
, field_type
)
1614 def get_field_by_name(self
, name
):
1616 Returns the :class:`FieldDeclaration` object named *name* in
1619 :exc:`TypeError` is raised on error.
1622 field_type_native
= nbt
._bt
_ctf
_event
_class
_get
_field
_by
_name
(self
._ec
, name
)
1624 if field_type_native
is None:
1625 msg
= "Could not find EventClass field with name {}".format(name
)
1626 raise TypeError(msg
)
1628 return FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1633 Events are specific instances of event classes
1634 (:class:`EventClass`), which means they may contain actual,
1635 concrete field values.
1638 def __init__(self
, event_class
):
1640 Creates an event linked with the :class:`EventClass`
1643 :exc:`ValueError` is raised on error.
1646 if not isinstance(event_class
, EventClass
):
1647 raise TypeError("Invalid event_class argument.")
1649 self
._e
= nbt
._bt
_ctf
_event
_create
(event_class
._ec
)
1652 raise ValueError("Event creation failed.")
1655 nbt
._bt
_ctf
_event
_put
(self
._e
)
1658 def event_class(self
):
1660 :class:`EventClass` object to which this event is linked.
1663 event_class_native
= nbt
._bt
_ctf
_event
_get
_class
(self
._e
)
1665 if event_class_native
is None:
1668 event_class
= EventClass
.__new
__(EventClass
)
1669 event_class
._ec
= event_class_native
1675 :class:`Clock` object used by this object, or ``None`` if
1676 the event class is not registered to a stream class.
1679 clock_instance
= nbt
._bt
_ctf
_event
_get
_clock
(self
._e
)
1681 if clock_instance
is None:
1684 clock
= Clock
.__new
__(Clock
)
1685 clock
._c
= clock_instance
1689 def payload(self
, field_name
):
1691 Returns the :class:`Field` object named *field_name* in this
1694 The returned field object is created using the event class'
1695 field declaration named *field_name*.
1697 The return type is one of:
1699 * :class:`IntegerField`
1700 * :class:`FloatingPointField`
1701 * :class:`EnumerationField`
1702 * :class:`StringField`
1703 * :class:`ArrayField`
1704 * :class:`SequenceField`
1705 * :class:`StructureField`
1706 * :class:`VariantField`
1708 :exc:`TypeError` is raised on error.
1711 native_instance
= nbt
._bt
_ctf
_event
_get
_payload
(self
._e
,
1714 if native_instance
is None:
1715 raise ValueError("Could not get event payload.")
1717 return Field
._create
_field
_from
_native
_instance
(native_instance
)
1719 def set_payload(self
, field_name
, value_field
):
1721 Set the event's field named *field_name* to the manually
1722 created :class:`Field` object *value_field*.
1724 *value_field*'s type must be one of:
1726 * :class:`IntegerField`
1727 * :class:`FloatingPointField`
1728 * :class:`EnumerationField`
1729 * :class:`StringField`
1730 * :class:`ArrayField`
1731 * :class:`SequenceField`
1732 * :class:`StructureField`
1733 * :class:`VariantField`
1735 :exc:`ValueError` is raised on error.
1738 if not isinstance(value
, Field
):
1739 raise TypeError("Invalid value type.")
1741 ret
= nbt
._bt
_ctf
_event
_set
_payload
(self
._e
, str(field_name
),
1745 raise ValueError("Could not set event field payload.")
1750 A stream class contains the properties of specific
1751 streams (:class:`Stream`). Any concrete stream must be linked with
1752 a :class:`StreamClass`, usually by calling
1753 :meth:`Writer.create_stream`.
1755 Some attributes are automatically set when creating a stream class.
1756 For example, if no clock is explicitly set using the
1757 :attr:`clock` attribute, a default clock will be created
1761 def __init__(self
, name
):
1763 Creates a stream class named *name*.
1765 :exc:`ValueError` is raised on error.
1768 self
._sc
= nbt
._bt
_ctf
_stream
_class
_create
(name
)
1770 if self
._sc
is None:
1771 raise ValueError("Stream class creation failed.")
1774 nbt
._bt
_ctf
_stream
_class
_put
(self
._sc
)
1781 :exc:`TypeError` is raised on error.
1784 name
= nbt
._bt
_ctf
_stream
_class
_get
_name
(self
._sc
)
1787 raise TypeError("Could not get StreamClass name")
1794 Stream class' clock (:class:`Clock` object).
1796 Set this attribute to change the clock of this stream class.
1798 :exc:`ValueError` is raised on error.
1801 clock_instance
= nbt
._bt
_ctf
_stream
_class
_get
_clock
(self
._sc
)
1803 if clock_instance
is None:
1806 clock
= Clock
.__new
__(Clock
)
1807 clock
._c
= clock_instance
1812 def clock(self
, clock
):
1813 if not isinstance(clock
, Clock
):
1814 raise TypeError("Invalid clock type.")
1816 ret
= nbt
._bt
_ctf
_stream
_class
_set
_clock
(self
._sc
, clock
._c
)
1819 raise ValueError("Could not set stream class clock.")
1824 Stream class' numeric ID.
1826 Set this attribute to change the ID of this stream class.
1828 :exc:`ValueError` is raised on error.
1831 ret
= nbt
._bt
_ctf
_stream
_class
_get
_id
(self
._sc
)
1834 raise TypeError("Could not get StreamClass id")
1840 ret
= nbt
._bt
_ctf
_stream
_class
_set
_id
(self
._sc
, id)
1843 raise TypeError("Could not set stream class id.")
1846 def event_classes(self
):
1848 Generates the event classes (:class:`EventClass` objects) of
1851 :exc:`TypeError` is raised on error.
1854 count
= nbt
._bt
_ctf
_stream
_class
_get
_event
_class
_count
(self
._sc
)
1857 raise TypeError("Could not get StreamClass' event class count")
1859 for i
in range(count
):
1860 event_class_native
= nbt
._bt
_ctf
_stream
_class
_get
_event
_class
(self
._sc
, i
)
1862 if event_class_native
is None:
1863 msg
= "Could not get StreamClass' event class at index {}".format(i
)
1864 raise TypeError(msg
)
1866 event_class
= EventClass
.__new
__(EventClass
)
1867 event_class
._ec
= event_class_native
1870 def add_event_class(self
, event_class
):
1872 Registers the :class:`EventClass` *event_class* to this stream
1875 Once the event class is registered, it will be generated as one
1876 of the event classes generated by :attr:`event_classes`.
1878 :exc:`ValueError` is raised on error.
1881 if not isinstance(event_class
, EventClass
):
1882 raise TypeError("Invalid event_class type.")
1884 ret
= nbt
._bt
_ctf
_stream
_class
_add
_event
_class
(self
._sc
,
1888 raise ValueError("Could not add event class.")
1891 def packet_context_type(self
):
1893 Stream packet context declaration.
1895 Set this attribute to change the stream packet context
1896 declaration (must be an instance of
1897 :class:`StructureFieldDeclaration`).
1899 :exc:`ValueError` is raised on error.
1903 field_type_native
= nbt
._bt
_ctf
_stream
_class
_get
_packet
_context
_type
(self
._sc
)
1905 if field_type_native
is None:
1906 raise ValueError("Invalid StreamClass")
1908 field_type
= FieldDeclaration
._create
_field
_declaration
_from
_native
_instance
(field_type_native
)
1912 @packet_context_type.setter
1913 def packet_context_type(self
, field_type
):
1914 if not isinstance(field_type
, StructureFieldDeclaration
):
1915 raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
1917 ret
= nbt
._bt
_ctf
_stream
_class
_set
_packet
_context
_type
(self
._sc
,
1921 raise ValueError("Failed to set packet context type.")
1926 Streams are specific instances of stream classes, which means they
1927 may contain actual, concrete events.
1929 :class:`Stream` objects are returned by
1930 :meth:`Writer.create_stream`; they are not meant to be
1931 instantiated by the user.
1933 Concrete :class:`Event` objects are appended to
1934 :class:`Stream` objects using :meth:`append_event`.
1936 When :meth:`flush` is called, a CTF packet is created, containing
1937 all the appended events since the last flush. Although the stream
1938 is flushed on object destruction, it is **strongly recommended**
1939 that the user call :meth:`flush` manually before exiting the
1940 script, as :meth:`__del__` is not always reliable.
1944 raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
1947 nbt
._bt
_ctf
_stream
_put
(self
._s
)
1950 def discarded_events(self
):
1952 Number of discarded (lost) events in this stream so far.
1954 :exc:`ValueError` is raised on error.
1957 ret
, count
= nbt
._bt
_ctf
_stream
_get
_discarded
_events
_count
(self
._s
)
1960 raise ValueError("Could not get the stream discarded events count")
1964 def append_discarded_events(self
, event_count
):
1966 Appends *event_count* discarded events to this stream.
1969 nbt
._bt
_ctf
_stream
_append
_discarded
_events
(self
._s
, event_count
)
1971 def append_event(self
, event
):
1973 Appends event *event* (:class:`Event` object) to this stream.
1975 The stream's associated clock will be sampled during this call.
1976 *event* **shall not** be modified after being appended to this
1979 :exc:`ValueError` is raised on error.
1982 ret
= nbt
._bt
_ctf
_stream
_append
_event
(self
._s
, event
._e
)
1985 raise ValueError("Could not append event to stream.")
1988 def packet_context(self
):
1990 Stream packet context field (instance of
1991 :class:`StructureField`).
1993 Set this attribute to assign a stream packet context field
1996 :exc:`ValueError` is raised on error.
1999 native_field
= nbt
._bt
_ctf
_stream
_get
_packet
_context
(self
._s
)
2001 if native_field
is None:
2002 raise ValueError("Invalid Stream.")
2004 return Field
._create
_field
_from
_native
_instance
(native_field
)
2006 @packet_context.setter
2007 def packet_context(self
, field
):
2008 if not isinstance(field
, StructureField
):
2009 raise TypeError("Argument field must be of type StructureField")
2011 ret
= nbt
._bt
_ctf
_stream
_set
_packet
_context
(self
._s
, field
._f
)
2014 raise ValueError("Invalid packet context field.")
2018 Flushes the current packet of this stream to disk. Events
2019 subsequently appended to the stream will be added to a new
2022 :exc:`ValueError` is raised on error.
2025 ret
= nbt
._bt
_ctf
_stream
_flush
(self
._s
)
2028 raise ValueError("Could not flush stream.")
2033 This object is the CTF writer API context. It oversees its streams
2034 and clocks, and is responsible for writing one CTF trace.
2037 def __init__(self
, path
):
2039 Creates a CTF writer, initializing a new CTF trace at path
2042 *path* must be an existing directory, since a CTF trace is
2043 made of multiple files.
2045 :exc:`ValueError` is raised if the creation fails.
2048 self
._w
= nbt
._bt
_ctf
_writer
_create
(path
)
2051 raise ValueError("Writer creation failed.")
2054 nbt
._bt
_ctf
_writer
_put
(self
._w
)
2056 def create_stream(self
, stream_class
):
2058 Creates and registers a new stream based on stream class
2061 This is the standard way of creating a :class:`Stream` object:
2062 the user is not allowed to instantiate this class.
2064 Returns a new :class:`Stream` object.
2067 if not isinstance(stream_class
, StreamClass
):
2068 raise TypeError("Invalid stream_class type.")
2070 stream
= Stream
.__new
__(Stream
)
2071 stream
._s
= nbt
._bt
_ctf
_writer
_create
_stream
(self
._w
, stream_class
._sc
)
2075 def add_environment_field(self
, name
, value
):
2077 Sets the CTF environment variable named *name* to value *value*
2078 (converted to a string).
2080 :exc:`ValueError` is raised on error.
2083 ret
= nbt
._bt
_ctf
_writer
_add
_environment
_field
(self
._w
, str(name
),
2087 raise ValueError("Could not add environment field to trace.")
2089 def add_clock(self
, clock
):
2091 Registers :class:`Clock` object *clock* to the writer.
2093 You *must* register CTF clocks assigned to stream classes
2096 :exc:`ValueError` is raised if the creation fails.
2099 ret
= nbt
._bt
_ctf
_writer
_add
_clock
(self
._w
, clock
._c
)
2102 raise ValueError("Could not add clock to Writer.")
2107 Current metadata of this trace (:class:`str`).
2110 return nbt
._bt
_ctf
_writer
_get
_metadata
_string
(self
._w
)
2112 def flush_metadata(self
):
2114 Flushes the trace's metadata to the metadata file.
2117 nbt
._bt
_ctf
_writer
_flush
_metadata
(self
._w
)
2120 def byte_order(self
):
2122 Native byte order of this trace (one of
2123 :class:`babeltrace.common.ByteOrder` constants).
2125 This is the actual byte order that is used when a field
2127 :attr:`babeltrace.common.ByteOrder.BYTE_ORDER_NATIVE`
2130 Set this attribute to change the trace's native byte order.
2132 Defaults to the host machine's endianness.
2134 :exc:`ValueError` is raised on error.
2137 raise NotImplementedError("Getter not implemented.")
2140 def byte_order(self
, byte_order
):
2141 ret
= nbt
._bt
_ctf
_writer
_set
_byte
_order
(self
._w
, byte_order
)
2144 raise ValueError("Could not set trace byte order.")