From 19ae15ed55fb6857ff469b60a3f3cbe32590c6e2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Mon, 18 Aug 2014 18:33:33 -0400 Subject: [PATCH] Fix Python: Add a comment warning about an API limitation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 --- bindings/python/babeltrace.i.in | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/bindings/python/babeltrace.i.in b/bindings/python/babeltrace.i.in index 5a06f0ba..5142952e 100644 --- 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() -- 2.34.1