56c022e2ce2a7772e7222e4c83afeb7fa9f7ee7b
1 #ifndef BABELTRACE2_GRAPH_INTERRUPTER_H
2 #define BABELTRACE2_GRAPH_INTERRUPTER_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
37 @defgroup api-intr Interrupter
43 An <strong><em>interrupter</em></strong> is a simple object which has
44 a single boolean state: set or not set.
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().
54 To interrupt a running trace processing graph or query:
56 -# Create an interrupter with bt_interrupter_create().
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().
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().
67 -# Run the graph with bt_graph_run() or perform the query with
68 bt_query_executor_query().
70 -# From a signal handler or another thread, call bt_interrupter_set() to
71 set the shared interrupter.
73 Eventually, the trace processing graph or query thread checks if it's
74 interrupted and stops processing, usually returning a status code which
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.
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.
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().
93 The type of an interrupter is #bt_interrupter.
102 @typedef struct bt_interrupter bt_interrupter;
117 Creates a default interrupter.
119 On success, the returned interrupter is \em not set
120 (bt_interrupter_is_set() returns #BT_FALSE).
123 New interrupter reference, or \c NULL on memory error.
125 extern bt_interrupter
*bt_interrupter_create(void);
136 Sets the interrupter \bt_p{interrupter}.
138 After you call this function, bt_interrupter_is_set() returns
141 @param[in] interrupter
144 @bt_pre_not_null{interrupter}
146 @sa bt_interrupter_reset() —
147 Resets an interrupter.
148 @sa bt_interrupter_is_set() —
149 Returns whether or not an interrupter is set.
151 extern void bt_interrupter_set(bt_interrupter
*interrupter
);
155 Resets the interrupter \bt_p{interrupter}.
157 After you call this function, bt_interrupter_is_set() returns
160 @param[in] interrupter
161 Interrupter to reset.
163 @bt_pre_not_null{interrupter}
165 @sa bt_interrupter_set() —
167 @sa bt_interrupter_is_set() —
168 Returns whether or not an interrupter is set.
170 extern void bt_interrupter_reset(bt_interrupter
*interrupter
);
174 Returns whether or not the interrupter \bt_p{interrupter} is set.
176 @param[in] interrupter
177 Interrupter to reset.
180 #BT_TRUE if \bt_p{interrupter} is set.
182 @bt_pre_not_null{interrupter}
184 @sa bt_interrupter_set() —
186 @sa bt_interrupter_reset() —
187 Resets an interrupter.
189 extern bt_bool
bt_interrupter_is_set(const bt_interrupter
*interrupter
);
194 @name Reference count
200 Increments the \ref api-fund-shared-object "reference count" of
201 the interrupter \bt_p{interrupter}.
203 @param[in] interrupter
205 Interrupter of which to increment the reference count.
210 @sa bt_interrupter_put_ref() —
211 Decrements the reference count of an interrupter.
213 extern void bt_interrupter_get_ref(const bt_interrupter
*interrupter
);
217 Decrements the \ref api-fund-shared-object "reference count" of
218 the interrupter \bt_p{interrupter}.
220 @param[in] interrupter
222 Interrupter of which to decrement the reference count.
227 @sa bt_interrupter_get_ref() —
228 Increments the reference count of an interrupter.
230 extern void bt_interrupter_put_ref(const bt_interrupter
*interrupter
);
234 Decrements the reference count of the interrupter
235 \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
239 Interrupter of which to decrement the reference count.
244 @bt_pre_assign_expr{_interrupter}
246 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter) \
248 bt_interrupter_put_ref(_interrupter); \
249 (_interrupter) = NULL; \
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.
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.
263 Destination expression.
274 @bt_pre_assign_expr{_dst}
275 @bt_pre_assign_expr{_src}
277 #define BT_INTERRUPTER_MOVE_REF(_dst, _src) \
279 bt_interrupter_put_ref(_dst); \
292 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */
This page took 0.036155 seconds and 3 git commands to generate.