X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace%2Fiterator.h;h=360a9c70a5a159eed3bd11b00e1bfa97060084c8;hp=df890f8ddbdfbcd69d7dfaa4a01f75823c05e09e;hb=c462e188f3e7819c7bc74f671038cdbf36e8c3c0;hpb=3353e841b83b27d0d5ff020c1ee0024c3d382b3e diff --git a/include/babeltrace/iterator.h b/include/babeltrace/iterator.h index df890f8d..360a9c70 100644 --- a/include/babeltrace/iterator.h +++ b/include/babeltrace/iterator.h @@ -15,93 +15,116 @@ * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. */ #include #include +#ifdef __cplusplus +extern "C" { +#endif + +/* Flags for the iterator read_event */ +enum { + BT_ITER_FLAG_LOST_EVENTS = (1 << 0), +}; + /* Forward declarations */ -struct babeltrace_iter; -struct ctf_stream_event; -struct ctf_stream; -struct babeltrace_saved_pos; +struct bt_iter; +struct bt_saved_pos; + +/* + * bt_iter is an abstract class, each format has to implement its own + * iterator derived from this parent class. + */ -struct trace_collection_pos { +/* + * 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 */ BT_SEEK_RESTORE, /* uses u.restore */ BT_SEEK_CUR, BT_SEEK_BEGIN, - BT_SEEK_END, + BT_SEEK_LAST, } 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); + +#ifdef __cplusplus +} +#endif #endif /* _BABELTRACE_ITERATOR_H */