Fix Python: Add a comment warning about an API limitation

Add a comment warning about a possible misuse of the events()
API. The objects returned by this function shall not be copied
as they become invalid as soon as the next event is accessed.

It is also invalid to access an event after its generator has
gone out of scope.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/bindings/python/babeltrace.i.in b/bindings/python/babeltrace.i.in
index 5a06f0ba4639db4ca12a76723b5c5198e5779be9..5142952ec5fdeac715a28e01510354b29ed68f07 100644 (file)
--- a/bindings/python/babeltrace.i.in
+++ b/bindings/python/babeltrace.i.in
@@ -211,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()