X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace%2Fiterator.h;h=e658eeec0b5cdc8789e684ca630b4c04d9396d67;hp=0acd91d431b2a98e59c7ad2e43c395dfc53166e2;hb=91f361c1757256c11988ab16376419a72592e1a9;hpb=dc81689e3a3b6facb2ffe89f0a0353a8eb0caeec

diff --git a/include/babeltrace/iterator.h b/include/babeltrace/iterator.h
index 0acd91d4..e658eeec 100644
--- a/include/babeltrace/iterator.h
+++ b/include/babeltrace/iterator.h
@@ -22,10 +22,32 @@
 
 /* Forward declarations */
 struct bt_iter;
-struct ctf_stream_event;
-struct ctf_stream;
 struct bt_saved_pos;
 
+/*
+ * bt_iter is an abstract class, each format has to implement its own
+ * iterator derived from this parent class.
+ */
+
+/*
+ * bt_iter_pos
+ *
+ * This structure represents the position where to set an iterator.
+ *
+ * type represents the type of seek to use.
+ * u is the argument of the seek if necessary :
+ * - seek_time is the real timestamp to seek to when using BT_SEEK_TIME, it
+ *   is expressed in nanoseconds
+ * - restore is a position saved with bt_iter_get_pos, it is used with
+ *   BT_SEEK_RESTORE.
+ *
+ * Note about BT_SEEK_LAST: if many events happen to be at the last
+ * timestamp, it is implementation-defined which event will be the last,
+ * and the order of events with the same timestamp may not be the same
+ * as normal iteration on the trace. Therefore, it is recommended to
+ * only use BT_SEEK_LAST to get the timestamp of the last event(s) in
+ * the trace.
+ */
 struct bt_iter_pos {
 	enum {
 		BT_SEEK_TIME,		/* uses u.seek_time */
@@ -33,6 +55,7 @@ struct bt_iter_pos {
 		BT_SEEK_CUR,
 		BT_SEEK_BEGIN,
 		BT_SEEK_END,
+		BT_SEEK_LAST,
 	} type;
 	union {
 		uint64_t seek_time;
@@ -40,27 +63,6 @@ struct bt_iter_pos {
 	} u;
 };
 
-/*
- * bt_iter_create - Allocate a trace collection iterator.
- *
- * begin_pos and end_pos are optional parameters to specify the position
- * at which the trace collection should be seeked upon iterator
- * creation, and the position at which iteration will start returning
- * "EOF".
- *
- * By default, if begin_pos is NULL, a BT_SEEK_CUR is performed at
- * creation. By default, if end_pos is NULL, a BT_SEEK_END (end of
- * trace) is the EOF criterion.
- */
-struct bt_iter *bt_iter_create(struct bt_context *ctx,
-		struct bt_iter_pos *begin_pos,
-		struct bt_iter_pos *end_pos);
-
-/*
- * bt_iter_destroy - Free a trace collection iterator.
- */
-void bt_iter_destroy(struct bt_iter *iter);
-
 /*
  * bt_iter_next: Move trace collection position to the next event.
  *
@@ -74,8 +76,7 @@ int bt_iter_next(struct bt_iter *iter);
  * The position returned by this function needs to be freed by
  * bt_iter_free_pos after use.
  */
-struct bt_iter_pos *
-	bt_iter_get_pos(struct bt_iter *iter);
+struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
 
 /*
  * bt_iter_free_pos - Free the position.
@@ -101,21 +102,9 @@ int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
  *
  * This function allocates and returns a new bt_iter_pos (which must be freed
  * with bt_iter_free_pos) to be able to restore an iterator position based on a
- * timestamp.
+ * real timestamp.
  */
 struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter,
 		uint64_t timestamp);
 
-/*
- * bt_iter_read_event: Read the iterator's current event data.
- *
- * @iter: trace collection iterator (input)
- * @stream: stream containing event at current position (output)
- * @event: current event (output)
- * Return 0 on success, negative error value on error.
- */
-int bt_iter_read_event(struct bt_iter *iter,
-		struct ctf_stream **stream,
-		struct ctf_stream_event **event);
-
 #endif /* _BABELTRACE_ITERATOR_H */