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