Commit | Line | Data |
---|---|---|
33573333 PP |
1 | #ifndef BABELTRACE2_GRAPH_INTERRUPTER_H |
2 | #define BABELTRACE2_GRAPH_INTERRUPTER_H | |
3 | ||
4 | /* | |
5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation | |
6 | * | |
7 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
8 | * of this software and associated documentation files (the "Software"), to deal | |
9 | * in the Software without restriction, including without limitation the rights | |
10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
11 | * copies of the Software, and to permit persons to whom the Software is | |
12 | * furnished to do so, subject to the following conditions: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in | |
15 | * all copies or substantial portions of the Software. | |
16 | * | |
17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
23 | * SOFTWARE. | |
24 | */ | |
25 | ||
26 | #ifndef __BT_IN_BABELTRACE_H | |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
30 | #include <babeltrace2/types.h> | |
31 | ||
32 | #ifdef __cplusplus | |
33 | extern "C" { | |
34 | #endif | |
35 | ||
7704a0af PP |
36 | /*! |
37 | @defgroup api-intr Interrupter | |
38 | @ingroup api-graph | |
39 | ||
40 | @brief | |
41 | Interrupter. | |
42 | ||
43 | An <strong><em>interrupter</em></strong> is a simple object which has | |
44 | a single boolean state: set or not set. | |
45 | ||
46 | You can use an interrupter to interrupt a running trace processing | |
47 | \bt_graph or \ref api-qexec "query". The user and library functions periodically | |
48 | check if they are interrupted (with | |
49 | bt_self_component_sink_is_interrupted(), | |
50 | bt_self_message_iterator_is_interrupted(), or | |
51 | bt_query_executor_is_interrupted()); meanwhile, another thread or | |
52 | a signal handler sets the shared interrupter with bt_interrupter_set(). | |
53 | ||
54 | To interrupt a running trace processing graph or query: | |
55 | ||
56 | -# Create an interrupter with bt_interrupter_create(). | |
57 | ||
58 | -# Before running a trace processing graph with bt_graph_run() or | |
59 | performing a query with bt_query_executor_query(), add | |
60 | the created interrupter to the object with bt_graph_add_interrupter() | |
61 | or bt_query_executor_add_interrupter(). | |
62 | ||
63 | Alternatively, you can borrow the existing, default interrupter from | |
64 | those objects with bt_graph_borrow_default_interrupter() and | |
65 | bt_query_executor_borrow_default_interrupter(). | |
66 | ||
67 | -# Run the graph with bt_graph_run() or perform the query with | |
68 | bt_query_executor_query(). | |
69 | ||
70 | -# From a signal handler or another thread, call bt_interrupter_set() to | |
71 | set the shared interrupter. | |
72 | ||
73 | Eventually, the trace processing graph or query thread checks if it's | |
74 | interrupted and stops processing, usually returning a status code which | |
75 | ends with \c _AGAIN. | |
76 | ||
77 | You can add more than one interrupter to a trace processing graph and | |
78 | to a query executor. The bt_self_component_sink_is_interrupted(), | |
79 | bt_self_message_iterator_is_interrupted(), and | |
80 | bt_query_executor_is_interrupted() functions return the logical | |
81 | disjunction of all the added interrupters's states, so that \em any | |
82 | interrupter can interrupt the thread. | |
83 | ||
84 | Once a trace processing graph or a query executor is interrupted and | |
85 | you get the thread's control back, you can reset the interrupter | |
86 | with bt_interrupter_reset() and continue the previous operation, | |
87 | calling bt_graph_run() or bt_query_executor_query() again. | |
88 | ||
89 | An interrupter is a \ref api-fund-shared-object "shared object": get a | |
90 | new reference with bt_interrupter_get_ref() and put an existing | |
91 | reference with bt_interrupter_put_ref(). | |
92 | ||
93 | The type of an interrupter is #bt_interrupter. | |
94 | */ | |
95 | ||
96 | /*! @{ */ | |
97 | ||
98 | /*! | |
99 | @name Type | |
100 | @{ | |
101 | ||
102 | @typedef struct bt_interrupter bt_interrupter; | |
103 | ||
104 | @brief | |
105 | Interrupter. | |
106 | ||
107 | @} | |
108 | */ | |
109 | ||
110 | /*! | |
111 | @name Creation | |
112 | @{ | |
113 | */ | |
114 | ||
115 | /*! | |
116 | @brief | |
117 | Creates a default interrupter. | |
118 | ||
119 | On success, the returned interrupter is \em not set | |
120 | (bt_interrupter_is_set() returns #BT_FALSE). | |
121 | ||
122 | @returns | |
123 | New interrupter reference, or \c NULL on memory error. | |
124 | */ | |
33573333 PP |
125 | extern bt_interrupter *bt_interrupter_create(void); |
126 | ||
7704a0af PP |
127 | /*! @} */ |
128 | ||
129 | /*! | |
130 | @name State | |
131 | @{ | |
132 | */ | |
133 | ||
134 | /*! | |
135 | @brief | |
136 | Sets the interrupter \bt_p{interrupter}. | |
137 | ||
138 | After you call this function, bt_interrupter_is_set() returns | |
139 | #BT_TRUE. | |
140 | ||
141 | @param[in] interrupter | |
142 | Interrupter to set. | |
143 | ||
144 | @bt_pre_not_null{interrupter} | |
145 | ||
146 | @sa bt_interrupter_reset() — | |
147 | Resets an interrupter. | |
148 | @sa bt_interrupter_is_set() — | |
149 | Returns whether or not an interrupter is set. | |
150 | */ | |
33573333 PP |
151 | extern void bt_interrupter_set(bt_interrupter *interrupter); |
152 | ||
7704a0af PP |
153 | /*! |
154 | @brief | |
155 | Resets the interrupter \bt_p{interrupter}. | |
156 | ||
157 | After you call this function, bt_interrupter_is_set() returns | |
158 | #BT_FALSE. | |
159 | ||
160 | @param[in] interrupter | |
161 | Interrupter to reset. | |
162 | ||
163 | @bt_pre_not_null{interrupter} | |
164 | ||
165 | @sa bt_interrupter_set() — | |
166 | Sets an interrupter. | |
167 | @sa bt_interrupter_is_set() — | |
168 | Returns whether or not an interrupter is set. | |
169 | */ | |
33573333 PP |
170 | extern void bt_interrupter_reset(bt_interrupter *interrupter); |
171 | ||
7704a0af PP |
172 | /*! |
173 | @brief | |
174 | Returns whether or not the interrupter \bt_p{interrupter} is set. | |
175 | ||
176 | @param[in] interrupter | |
177 | Interrupter to reset. | |
178 | ||
179 | @returns | |
180 | #BT_TRUE if \bt_p{interrupter} is set. | |
181 | ||
182 | @bt_pre_not_null{interrupter} | |
183 | ||
184 | @sa bt_interrupter_set() — | |
185 | Sets an interrupter. | |
186 | @sa bt_interrupter_reset() — | |
187 | Resets an interrupter. | |
188 | */ | |
189 | extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter); | |
190 | ||
191 | /*! @} */ | |
192 | ||
193 | /*! | |
194 | @name Reference count | |
195 | @{ | |
196 | */ | |
197 | ||
198 | /*! | |
199 | @brief | |
200 | Increments the \ref api-fund-shared-object "reference count" of | |
201 | the interrupter \bt_p{interrupter}. | |
202 | ||
203 | @param[in] interrupter | |
204 | @parblock | |
205 | Interrupter of which to increment the reference count. | |
206 | ||
207 | Can be \c NULL. | |
208 | @endparblock | |
209 | ||
210 | @sa bt_interrupter_put_ref() — | |
211 | Decrements the reference count of an interrupter. | |
212 | */ | |
213 | extern void bt_interrupter_get_ref(const bt_interrupter *interrupter); | |
214 | ||
215 | /*! | |
216 | @brief | |
217 | Decrements the \ref api-fund-shared-object "reference count" of | |
218 | the interrupter \bt_p{interrupter}. | |
219 | ||
220 | @param[in] interrupter | |
221 | @parblock | |
222 | Interrupter of which to decrement the reference count. | |
223 | ||
224 | Can be \c NULL. | |
225 | @endparblock | |
226 | ||
227 | @sa bt_interrupter_get_ref() — | |
228 | Increments the reference count of an interrupter. | |
229 | */ | |
230 | extern void bt_interrupter_put_ref(const bt_interrupter *interrupter); | |
231 | ||
232 | /*! | |
233 | @brief | |
234 | Decrements the reference count of the interrupter | |
235 | \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL. | |
236 | ||
237 | @param _interrupter | |
238 | @parblock | |
239 | Interrupter of which to decrement the reference count. | |
240 | ||
241 | Can contain \c NULL. | |
242 | @endparblock | |
243 | ||
244 | @bt_pre_assign_expr{_interrupter} | |
245 | */ | |
246 | #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter) \ | |
247 | do { \ | |
248 | bt_interrupter_put_ref(_interrupter); \ | |
249 | (_interrupter) = NULL; \ | |
250 | } while (0) | |
251 | ||
252 | /*! | |
253 | @brief | |
254 | Decrements the reference count of the interrupter \bt_p{_dst}, sets | |
255 | \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL. | |
256 | ||
257 | This macro effectively moves an interrupter reference from the | |
258 | expression \bt_p{_src} to the expression \bt_p{_dst}, putting the | |
259 | existing \bt_p{_dst} reference. | |
260 | ||
261 | @param _dst | |
262 | @parblock | |
263 | Destination expression. | |
264 | ||
265 | Can contain \c NULL. | |
266 | @endparblock | |
267 | @param _src | |
268 | @parblock | |
269 | Source expression. | |
270 | ||
271 | Can contain \c NULL. | |
272 | @endparblock | |
273 | ||
274 | @bt_pre_assign_expr{_dst} | |
275 | @bt_pre_assign_expr{_src} | |
276 | */ | |
277 | #define BT_INTERRUPTER_MOVE_REF(_dst, _src) \ | |
278 | do { \ | |
279 | bt_interrupter_put_ref(_dst); \ | |
280 | (_dst) = (_src); \ | |
281 | (_src) = NULL; \ | |
282 | } while (0) | |
283 | ||
284 | /*! @} */ | |
285 | ||
286 | /*! @} */ | |
287 | ||
33573333 PP |
288 | #ifdef __cplusplus |
289 | } | |
290 | #endif | |
291 | ||
292 | #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */ |