[babeltrace.git] / include / babeltrace2 / graph / interrupter.h

#ifndef BABELTRACE2_GRAPH_INTERRUPTER_H
#define BABELTRACE2_GRAPH_INTERRUPTER_H

/*
 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <babeltrace2/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-intr Interrupter
@ingroup api-graph

@brief
    Interrupter.

An <strong><em>interrupter</em></strong> is a simple object which has
a single boolean state: set or not set.

You can use an interrupter to interrupt a running trace processing
\bt_graph or \ref api-qexec "query". The user and library functions periodically
check if they are interrupted (with
bt_self_component_sink_is_interrupted(),
bt_self_message_iterator_is_interrupted(), or
bt_query_executor_is_interrupted()); meanwhile, another thread or
a signal handler sets the shared interrupter with bt_interrupter_set().

To interrupt a running trace processing graph or query:

-# Create an interrupter with bt_interrupter_create().

-# Before running a trace processing graph with bt_graph_run() or
   performing a query with bt_query_executor_query(), add
   the created interrupter to the object with bt_graph_add_interrupter()
   or bt_query_executor_add_interrupter().

   Alternatively, you can borrow the existing, default interrupter from
   those objects with bt_graph_borrow_default_interrupter() and
   bt_query_executor_borrow_default_interrupter().

-# Run the graph with bt_graph_run() or perform the query with
   bt_query_executor_query().

-# From a signal handler or another thread, call bt_interrupter_set() to
   set the shared interrupter.

Eventually, the trace processing graph or query thread checks if it's
interrupted and stops processing, usually returning a status code which
ends with \c _AGAIN.

You can add more than one interrupter to a trace processing graph and
to a query executor. The bt_self_component_sink_is_interrupted(),
bt_self_message_iterator_is_interrupted(), and
bt_query_executor_is_interrupted() functions return the logical
disjunction of all the added interrupters's states, so that \em any
interrupter can interrupt the thread.

Once a trace processing graph or a query executor is interrupted and
you get the thread's control back, you can reset the interrupter
with bt_interrupter_reset() and continue the previous operation,
calling bt_graph_run() or bt_query_executor_query() again.

An interrupter is a \ref api-fund-shared-object "shared object": get a
new reference with bt_interrupter_get_ref() and put an existing
reference with bt_interrupter_put_ref().

The type of an interrupter is #bt_interrupter.
*/

/*! @{ */

/*!
@name Type
@{

@typedef struct bt_interrupter bt_interrupter;

@brief
    Interrupter.

@}
*/

/*!
@name Creation
@{
*/

/*!
@brief
    Creates a default interrupter.

On success, the returned interrupter is \em not set
(bt_interrupter_is_set() returns #BT_FALSE).

@returns
    New interrupter reference, or \c NULL on memory error.
*/
extern bt_interrupter *bt_interrupter_create(void);

/*! @} */

/*!
@name State
@{
*/

/*!
@brief
    Sets the interrupter \bt_p{interrupter}.

After you call this function, bt_interrupter_is_set() returns
#BT_TRUE.

@param[in] interrupter
    Interrupter to set.

@bt_pre_not_null{interrupter}

@sa bt_interrupter_reset() &mdash;
    Resets an interrupter.
@sa bt_interrupter_is_set() &mdash;
    Returns whether or not an interrupter is set.
*/
extern void bt_interrupter_set(bt_interrupter *interrupter);

/*!
@brief
    Resets the interrupter \bt_p{interrupter}.

After you call this function, bt_interrupter_is_set() returns
#BT_FALSE.

@param[in] interrupter
    Interrupter to reset.

@bt_pre_not_null{interrupter}

@sa bt_interrupter_set() &mdash;
    Sets an interrupter.
@sa bt_interrupter_is_set() &mdash;
    Returns whether or not an interrupter is set.
*/
extern void bt_interrupter_reset(bt_interrupter *interrupter);

/*!
@brief
    Returns whether or not the interrupter \bt_p{interrupter} is set.

@param[in] interrupter
    Interrupter to reset.

@returns
    #BT_TRUE if \bt_p{interrupter} is set.

@bt_pre_not_null{interrupter}

@sa bt_interrupter_set() &mdash;
    Sets an interrupter.
@sa bt_interrupter_reset() &mdash;
    Resets an interrupter.
*/
extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter);

/*! @} */

/*!
@name Reference count
@{
*/

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the interrupter \bt_p{interrupter}.

@param[in] interrupter
    @parblock
    Interrupter of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_interrupter_put_ref() &mdash;
    Decrements the reference count of an interrupter.
*/
extern void bt_interrupter_get_ref(const bt_interrupter *interrupter);

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the interrupter \bt_p{interrupter}.

@param[in] interrupter
    @parblock
    Interrupter of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_interrupter_get_ref() &mdash;
    Increments the reference count of an interrupter.
*/
extern void bt_interrupter_put_ref(const bt_interrupter *interrupter);

/*!
@brief
    Decrements the reference count of the interrupter
    \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.

@param _interrupter
    @parblock
    Interrupter of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_interrupter}
*/
#define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)	\
	do {						\
		bt_interrupter_put_ref(_interrupter);	\
		(_interrupter) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the interrupter \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves an interrupter reference from the
expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
existing \bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_INTERRUPTER_MOVE_REF(_dst, _src)	\
	do {					\
		bt_interrupter_put_ref(_dst);	\
		(_dst) = (_src);		\
		(_src) = NULL;			\
	} while (0)

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */
Commit	Line	Data
b70d57a1 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
43c59509 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	*/
b70d57a1 PP	125	extern bt_interrupter *bt_interrupter_create(void);
b70d57a1 PP	126
43c59509 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	*/
b70d57a1 PP	151	extern void bt_interrupter_set(bt_interrupter *interrupter);
b70d57a1 PP	152
43c59509 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	*/
b70d57a1 PP	170	extern void bt_interrupter_reset(bt_interrupter *interrupter);
b70d57a1 PP	171
43c59509 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
b70d57a1 PP	288	#ifdef __cplusplus
	289	}
	290	#endif
	291
	292	#endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */