Fix Python: Add a comment warning about an API limitation

[babeltrace.git] / bindings / python / babeltrace.i.in

diff --git a/bindings/python/babeltrace.i.in b/bindings/python/babeltrace.i.in
index c0dd3a0994424ba56dc962ac6c455904b2807f91..5142952ec5fdeac715a28e01510354b29ed68f07 100644 (file)
--- a/bindings/python/babeltrace.i.in
+++ b/bindings/python/babeltrace.i.in
@@ -93,7 +93,10 @@ struct definition_sequence *_bt_python_get_sequence_from_def(
                struct bt_definition *field);
 struct bt_declaration *_bt_python_get_array_element_declaration(
                struct bt_declaration *field);
+struct bt_declaration *_bt_python_get_sequence_element_declaration(
+               struct bt_declaration *field);
 const char *_bt_python_get_array_string(struct bt_definition *field);
+const char *_bt_python_get_sequence_string(struct bt_definition *field);
 int _bt_python_field_integer_get_signedness(const struct bt_ctf_field *field);
 enum ctf_type_id _bt_python_get_field_type(const struct bt_ctf_field *field);
 
@@ -208,6 +211,17 @@ class TraceCollection:
                """
                Generator function to iterate over the events of open in the current
                TraceCollection.
+
+               Due to limitations of the native Babeltrace API, only one event
+               may be "alive" at a time (i.e. a user should never store a copy
+               of the events returned by this function for ulterior use). Users
+               shall make sure to copy the information they need from an event
+               before accessing the next one.
+
+               Furthermore, event objects become invalid when the generator goes
+               out of scope as the underlying iterator will be reclaimed. Using an
+               event after the the generator has gone out of scope may result in a
+               crash or data corruption.
                """
                begin_pos_ptr = _bt_iter_pos()
                end_pos_ptr = _bt_iter_pos()
@@ -952,6 +966,14 @@ class SequenceFieldDeclaration(FieldDeclaration):
        def __init__(self):
                raise NotImplementedError("SequenceFieldDeclaration cannot be instantiated")
 
+       @property
+       def element_declaration(self):
+               """
+               Return element declaration.
+               """
+               field_decl_ptr = _bt_python_get_sequence_element_declaration(self._fd)
+               return _create_field_declaration(field_decl_ptr, "", self.scope)
+
 class FloatFieldDeclaration(FieldDeclaration):
        """Do not instantiate."""
        def __init__(self):
@@ -1179,11 +1201,17 @@ class _Definition(object):
                elif id == CTFTypeId.ENUM:
                        value = self._get_enum_str()
                elif id == CTFTypeId.SEQUENCE:
-                       seq_len = self._get_sequence_len()
-                       value = []
-                       for i in range(seq_len):
-                               evDef = self._get_sequence_element_at(i)
-                               value.append(evDef.value)
+                       element_decl = self.declaration.element_declaration
+                       if ((element_decl.type == CTFTypeId.INTEGER
+                               and element_decl.length == 8)
+                               and (element_decl.encoding == CTFStringEncoding.ASCII or element_decl.encoding == CTFStringEncoding.UTF8)):
+                               value = _bt_python_get_sequence_string(self._d)
+                       else:
+                               seq_len = self._get_sequence_len()
+                               value = []
+                               for i in range(seq_len):
+                                       evDef = self._get_sequence_element_at(i)
+                                       value.append(evDef.value)
                elif id == CTFTypeId.FLOAT:
                        value = self._get_float()
                elif id == CTFTypeId.VARIANT: