2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_INTERRUPTER_H
8 #define BABELTRACE2_GRAPH_INTERRUPTER_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
23 @defgroup api-intr Interrupter
29 An <strong><em>interrupter</em></strong> is a simple object which has
30 a single boolean state: set or not set.
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().
40 To interrupt a running trace processing graph or query:
42 -# Create an interrupter with bt_interrupter_create().
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().
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().
53 -# Run the graph with bt_graph_run() or perform the query with
54 bt_query_executor_query().
56 -# From a signal handler or another thread, call bt_interrupter_set() to
57 set the shared interrupter.
59 Eventually, the trace processing graph or query thread checks if it's
60 interrupted and stops processing, usually returning a status code which
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.
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.
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().
79 The type of an interrupter is #bt_interrupter.
88 @typedef struct bt_interrupter bt_interrupter;
103 Creates a default interrupter.
105 On success, the returned interrupter is \em not set
106 (bt_interrupter_is_set() returns #BT_FALSE).
109 New interrupter reference, or \c NULL on memory error.
111 extern bt_interrupter
*bt_interrupter_create(void);
122 Sets the interrupter \bt_p{interrupter}.
124 After you call this function, bt_interrupter_is_set() returns
127 @param[in] interrupter
130 @bt_pre_not_null{interrupter}
132 @sa bt_interrupter_reset() —
133 Resets an interrupter.
134 @sa bt_interrupter_is_set() —
135 Returns whether or not an interrupter is set.
137 extern void bt_interrupter_set(bt_interrupter
*interrupter
);
141 Resets the interrupter \bt_p{interrupter}.
143 After you call this function, bt_interrupter_is_set() returns
146 @param[in] interrupter
147 Interrupter to reset.
149 @bt_pre_not_null{interrupter}
151 @sa bt_interrupter_set() —
153 @sa bt_interrupter_is_set() —
154 Returns whether or not an interrupter is set.
156 extern void bt_interrupter_reset(bt_interrupter
*interrupter
);
160 Returns whether or not the interrupter \bt_p{interrupter} is set.
162 @param[in] interrupter
163 Interrupter to reset.
166 #BT_TRUE if \bt_p{interrupter} is set.
168 @bt_pre_not_null{interrupter}
170 @sa bt_interrupter_set() —
172 @sa bt_interrupter_reset() —
173 Resets an interrupter.
175 extern bt_bool
bt_interrupter_is_set(const bt_interrupter
*interrupter
);
180 @name Reference count
186 Increments the \ref api-fund-shared-object "reference count" of
187 the interrupter \bt_p{interrupter}.
189 @param[in] interrupter
191 Interrupter of which to increment the reference count.
196 @sa bt_interrupter_put_ref() —
197 Decrements the reference count of an interrupter.
199 extern void bt_interrupter_get_ref(const bt_interrupter
*interrupter
);
203 Decrements the \ref api-fund-shared-object "reference count" of
204 the interrupter \bt_p{interrupter}.
206 @param[in] interrupter
208 Interrupter of which to decrement the reference count.
213 @sa bt_interrupter_get_ref() —
214 Increments the reference count of an interrupter.
216 extern void bt_interrupter_put_ref(const bt_interrupter
*interrupter
);
220 Decrements the reference count of the interrupter
221 \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
225 Interrupter of which to decrement the reference count.
230 @bt_pre_assign_expr{_interrupter}
232 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter) \
234 bt_interrupter_put_ref(_interrupter); \
235 (_interrupter) = NULL; \
240 Decrements the reference count of the interrupter \bt_p{_dst}, sets
241 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
243 This macro effectively moves an interrupter reference from the
244 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
245 existing \bt_p{_dst} reference.
249 Destination expression.
260 @bt_pre_assign_expr{_dst}
261 @bt_pre_assign_expr{_src}
263 #define BT_INTERRUPTER_MOVE_REF(_dst, _src) \
265 bt_interrupter_put_ref(_dst); \
278 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */
This page took 0.040587 seconds and 5 git commands to generate.