Notification iterator: generate automatic notifications when missing
[babeltrace.git] / include / babeltrace / graph / notification-iterator.h
1 #ifndef BABELTRACE_COMPONENT_NOTIFICATION_ITERATOR_H
2 #define BABELTRACE_COMPONENT_NOTIFICATION_ITERATOR_H
3
4 /*
5 * BabelTrace - Plug-in Notification Iterator
6 *
7 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 */
29
30 #include <stdint.h>
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 struct bt_notification;
37 struct bt_notification_iterator;
38
39 /**
40 * Status code. Errors are always negative.
41 */
42 enum bt_notification_iterator_status {
43 /** Try again. */
44 BT_NOTIFICATION_ITERATOR_STATUS_AGAIN = 11,
45 /** No more notifications to be delivered. */
46 BT_NOTIFICATION_ITERATOR_STATUS_END = 1,
47 /** No error, okay. */
48 BT_NOTIFICATION_ITERATOR_STATUS_OK = 0,
49 /** Invalid arguments. */
50 BT_NOTIFICATION_ITERATOR_STATUS_INVALID = -22,
51 /** General error. */
52 BT_NOTIFICATION_ITERATOR_STATUS_ERROR = -1,
53 /** Out of memory. */
54 BT_NOTIFICATION_ITERATOR_STATUS_NOMEM = -12,
55 /** Unsupported iterator feature. */
56 BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED = -2,
57 };
58
59 /**
60 * Notification iterator seek reference.
61 */
62 enum bt_notification_iterator_seek_origin {
63 /** Seek at a time relative to the beginning of the trace. */
64 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_BEGIN = 0,
65
66 /** Seek at a time relative to the current position. */
67 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_CURRENT = 1,
68
69 /** Seek at a time relative to the end of the trace. */
70 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_END = 2,
71
72 /** Seek at a time relative to EPOCH. */
73 BT_NOTIFICATION_ITERATOR_SEEK_ORIGIN_EPOCH = 3,
74 };
75
76 struct bt_notification_iterator_next_return {
77 struct bt_notification *notification;
78 enum bt_notification_iterator_status status;
79 };
80
81 /**
82 * Get current notification at iterator's position.
83 *
84 * This functions will <b>not</b> advance the cursor's position.
85 * The returned notification's reference count is already incremented.
86 *
87 * @param iterator Iterator instance
88 * @returns Returns a bt_notification instance
89 *
90 * @see bt_put()
91 */
92 extern struct bt_notification *bt_notification_iterator_get_notification(
93 struct bt_notification_iterator *iterator);
94
95 /**
96 * Advance the iterator's position forward.
97 *
98 * This function can be called repeatedly to iterate through the iterator's
99 * associated trace.
100 *
101 * @param iterator Iterator instance
102 * @returns Returns a bt_notification instance
103 *
104 * @see bt_notification_iterator_get_notification()
105 */
106 extern enum bt_notification_iterator_status
107 bt_notification_iterator_next(struct bt_notification_iterator *iterator);
108
109 /**
110 * Seek iterator to time.
111 *
112 * Sets the iterator's position for the trace associated with the iterator.
113 * The new position is computed by adding \p time to the position specified
114 * by \p seek_origin.
115 *
116 * time is expressed in nanoseconds.
117 *
118 * @param iterator Iterator instance
119 * @param seek_origin One of #bt_notification_iterator_seek_type values.
120 * @returns One of #bt_notification_iterator_status values;
121 * if \iterator does not support seeking,
122 * #BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED is
123 * returned.
124 *
125 * @see bt_notification_iterator_get_notification()
126 */
127 extern enum bt_notification_iterator_status bt_notification_iterator_seek_time(
128 struct bt_notification_iterator *iterator,
129 enum bt_notification_iterator_seek_origin seek_origin,
130 int64_t time);
131
132 extern struct bt_component *bt_notification_iterator_get_component(
133 struct bt_notification_iterator *iterator);
134
135 #ifdef __cplusplus
136 }
137 #endif
138
139 #endif /* BABELTRACE_COMPONENT_NOTIFICATION_ITERATOR_H */
This page took 0.03188 seconds and 4 git commands to generate.