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) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
) __BT_NOEXCEPT
;
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
)
181 @name Reference count
187 Increments the \ref api-fund-shared-object "reference count" of
188 the interrupter \bt_p{interrupter}.
190 @param[in] interrupter
192 Interrupter of which to increment the reference count.
197 @sa bt_interrupter_put_ref() —
198 Decrements the reference count of an interrupter.
200 extern void bt_interrupter_get_ref(const bt_interrupter
*interrupter
)
205 Decrements the \ref api-fund-shared-object "reference count" of
206 the interrupter \bt_p{interrupter}.
208 @param[in] interrupter
210 Interrupter of which to decrement the reference count.
215 @sa bt_interrupter_get_ref() —
216 Increments the reference count of an interrupter.
218 extern void bt_interrupter_put_ref(const bt_interrupter
*interrupter
)
223 Decrements the reference count of the interrupter
224 \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
228 Interrupter of which to decrement the reference count.
233 @bt_pre_assign_expr{_interrupter}
235 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter) \
237 bt_interrupter_put_ref(_interrupter); \
238 (_interrupter) = NULL; \
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.
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.
252 Destination expression.
263 @bt_pre_assign_expr{_dst}
264 @bt_pre_assign_expr{_src}
266 #define BT_INTERRUPTER_MOVE_REF(_dst, _src) \
268 bt_interrupter_put_ref(_dst); \
281 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */
This page took 0.034906 seconds and 4 git commands to generate.