Get rid of clock-raw and use real clock

[babeltrace.git] / include / babeltrace / iterator.h

diff --git a/include/babeltrace/iterator.h b/include/babeltrace/iterator.h
index 923d2e1757ca1225633f2e0d12474e2b2cf119ff..8c106ccb16cb0b76500264d8ae38b6f97a362ab3 100644 (file)
--- a/include/babeltrace/iterator.h
+++ b/include/babeltrace/iterator.h
@@ -20,15 +20,28 @@
 #include <babeltrace/format.h>
 #include <babeltrace/context.h>
 
-typedef GQuark bt_event_name;
-
 /* Forward declarations */
-struct babeltrace_iter;
-struct ctf_stream_event;
-struct ctf_stream;
-struct babeltrace_saved_pos;
+struct bt_iter;
+struct bt_saved_pos;
 
-struct trace_collection_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 "raw" seconds (not offsetted)
+ * - restore is a position saved with bt_iter_get_pos, it is used with
+ *   BT_SEEK_RESTORE.
+ */
+struct bt_iter_pos {
        enum {
                BT_SEEK_TIME,           /* uses u.seek_time */
                BT_SEEK_RESTORE,        /* uses u.restore */
@@ -38,72 +51,52 @@ struct trace_collection_pos {
        } type;
        union {
                uint64_t seek_time;
-               struct babeltrace_saved_pos *restore;
+               struct bt_saved_pos *restore;
        } u;
 };
 
 /*
- * babeltrace_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 babeltrace_iter *babeltrace_iter_create(struct bt_context *ctx,
-               struct trace_collection_pos *begin_pos,
-               struct trace_collection_pos *end_pos);
-
-/*
- * babeltrace_iter_destroy - Free a trace collection iterator.
- */
-void babeltrace_iter_destroy(struct babeltrace_iter *iter);
-
-/*
- * babeltrace_iter_next: Move trace collection position to the next event.
+ * bt_iter_next: Move trace collection position to the next event.
  *
  * Returns 0 on success, a negative value on error
  */
-int babeltrace_iter_next(struct babeltrace_iter *iter);
+int bt_iter_next(struct bt_iter *iter);
 
 /*
- * babeltrace_iter_save_pos - Save the current trace collection position.
+ * bt_iter_get_pos - Get the current iterator position.
  *
  * The position returned by this function needs to be freed by
- * babeltrace_iter_free_pos after use.
+ * bt_iter_free_pos after use.
  */
-struct trace_collection_pos *
-       babeltrace_iter_save_pos(struct babeltrace_iter *iter);
+struct bt_iter_pos *bt_iter_get_pos(struct bt_iter *iter);
 
 /*
- * babeltrace_iter_free_pos - Free the position.
+ * bt_iter_free_pos - Free the position.
  */
-void babeltrace_iter_free_pos(struct trace_collection_pos *pos);
+void bt_iter_free_pos(struct bt_iter_pos *pos);
 
 /*
- * babeltrace_iter_seek: seek iterator to given position.
+ * bt_iter_set_pos: move the iterator to a given position.
+ *
+ * On error, the stream_heap is reinitialized and returned empty.
  *
- * Return EOF if position is after the last event of the trace collection.
- * Return other negative value for other errors.
  * Return 0 for success.
+ *
+ * Return EOF if the position requested is after the last event of the
+ * trace collection.
+ * Return -EINVAL when called with invalid parameter.
+ * Return -ENOMEM if the stream_heap could not be properly initialized.
  */
-int babeltrace_iter_seek(struct babeltrace_iter *iter,
-               const struct trace_collection_pos *pos);
+int bt_iter_set_pos(struct bt_iter *iter, const struct bt_iter_pos *pos);
 
 /*
- * babeltrace_iter_read_event: Read the iterator's current event data.
+ * bt_iter_create_time_pos: create a position based on time
  *
- * @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.
+ * 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
+ * real timestamp.
  */
-int babeltrace_iter_read_event(struct babeltrace_iter *iter,
-               struct ctf_stream **stream,
-               struct ctf_stream_event **event);
+struct bt_iter_pos *bt_iter_create_time_pos(struct bt_iter *iter,
+               uint64_t timestamp);
 
 #endif /* _BABELTRACE_ITERATOR_H */