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() —
+ Resets an interrupter.
+@sa bt_interrupter_is_set() —
+ 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() —
+ Sets an interrupter.
+@sa bt_interrupter_is_set() —
+ 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() —
+ Sets an interrupter.
+@sa bt_interrupter_reset() —
+ 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() —
+ 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() —
+ 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
projects / babeltrace.git / blobdiff