include/babeltrace2/graph/interrupter.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_INTERRUPTER_H
   8 #define BABELTRACE2_GRAPH_INTERRUPTER_H
   9
  10 #ifndef __BT_IN_BABELTRACE_H
  11 # error "Please include <babeltrace2/babeltrace.h> instead."
  12 #endif
  13
  14 #include <babeltrace2/types.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /*!
  21 @defgroup api-intr Interrupter
  22 @ingroup api-graph
  23
  24 @brief
  25     Interrupter.
  26
  27 An <strong><em>interrupter</em></strong> is a simple object which has
  28 a single boolean state: set or not set.
  29
  30 You can use an interrupter to interrupt a running trace processing
  31 \bt_graph or \ref api-qexec "query". The user and library functions periodically
  32 check if they are interrupted (with
  33 bt_self_component_sink_is_interrupted(),
  34 bt_self_message_iterator_is_interrupted(), or
  35 bt_query_executor_is_interrupted()); meanwhile, another thread or
  36 a signal handler sets the shared interrupter with bt_interrupter_set().
  37
  38 To interrupt a running trace processing graph or query:
  39
  40 -# Create an interrupter with bt_interrupter_create().
  41
  42 -# Before running a trace processing graph with bt_graph_run() or
  43    performing a query with bt_query_executor_query(), add
  44    the created interrupter to the object with bt_graph_add_interrupter()
  45    or bt_query_executor_add_interrupter().
  46
  47    Alternatively, you can borrow the existing, default interrupter from
  48    those objects with bt_graph_borrow_default_interrupter() and
  49    bt_query_executor_borrow_default_interrupter().
  50
  51 -# Run the graph with bt_graph_run() or perform the query with
  52    bt_query_executor_query().
  53
  54 -# From a signal handler or another thread, call bt_interrupter_set() to
  55    set the shared interrupter.
  56
  57 Eventually, the trace processing graph or query thread checks if it's
  58 interrupted and stops processing, usually returning a status code which
  59 ends with \c _AGAIN.
  60
  61 You can add more than one interrupter to a trace processing graph and
  62 to a query executor. The bt_self_component_sink_is_interrupted(),
  63 bt_self_message_iterator_is_interrupted(), and
  64 bt_query_executor_is_interrupted() functions return the logical
  65 disjunction of all the added interrupters's states, so that \em any
  66 interrupter can interrupt the thread.
  67
  68 Once a trace processing graph or a query executor is interrupted and
  69 you get the thread's control back, you can reset the interrupter
  70 with bt_interrupter_reset() and continue the previous operation,
  71 calling bt_graph_run() or bt_query_executor_query() again.
  72
  73 An interrupter is a \ref api-fund-shared-object "shared object": get a
  74 new reference with bt_interrupter_get_ref() and put an existing
  75 reference with bt_interrupter_put_ref().
  76
  77 The type of an interrupter is #bt_interrupter.
  78 */
  79
  80 /*! @{ */
  81
  82 /*!
  83 @name Type
  84 @{
  85
  86 @typedef struct bt_interrupter bt_interrupter;
  87
  88 @brief
  89     Interrupter.
  90
  91 @}
  92 */
  93
  94 /*!
  95 @name Creation
  96 @{
  97 */
  98
  99 /*!
 100 @brief
 101     Creates a default interrupter.
 102
 103 On success, the returned interrupter is \em not set
 104 (bt_interrupter_is_set() returns #BT_FALSE).
 105
 106 @returns
 107     New interrupter reference, or \c NULL on memory error.
 108 */
 109 extern bt_interrupter *bt_interrupter_create(void);
 110
 111 /*! @} */
 112
 113 /*!
 114 @name State
 115 @{
 116 */
 117
 118 /*!
 119 @brief
 120     Sets the interrupter \bt_p{interrupter}.
 121
 122 After you call this function, bt_interrupter_is_set() returns
 123 #BT_TRUE.
 124
 125 @param[in] interrupter
 126     Interrupter to set.
 127
 128 @bt_pre_not_null{interrupter}
 129
 130 @sa bt_interrupter_reset() &mdash;
 131     Resets an interrupter.
 132 @sa bt_interrupter_is_set() &mdash;
 133     Returns whether or not an interrupter is set.
 134 */
 135 extern void bt_interrupter_set(bt_interrupter *interrupter);
 136
 137 /*!
 138 @brief
 139     Resets the interrupter \bt_p{interrupter}.
 140
 141 After you call this function, bt_interrupter_is_set() returns
 142 #BT_FALSE.
 143
 144 @param[in] interrupter
 145     Interrupter to reset.
 146
 147 @bt_pre_not_null{interrupter}
 148
 149 @sa bt_interrupter_set() &mdash;
 150     Sets an interrupter.
 151 @sa bt_interrupter_is_set() &mdash;
 152     Returns whether or not an interrupter is set.
 153 */
 154 extern void bt_interrupter_reset(bt_interrupter *interrupter);
 155
 156 /*!
 157 @brief
 158     Returns whether or not the interrupter \bt_p{interrupter} is set.
 159
 160 @param[in] interrupter
 161     Interrupter to reset.
 162
 163 @returns
 164     #BT_TRUE if \bt_p{interrupter} is set.
 165
 166 @bt_pre_not_null{interrupter}
 167
 168 @sa bt_interrupter_set() &mdash;
 169     Sets an interrupter.
 170 @sa bt_interrupter_reset() &mdash;
 171     Resets an interrupter.
 172 */
 173 extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter);
 174
 175 /*! @} */
 176
 177 /*!
 178 @name Reference count
 179 @{
 180 */
 181
 182 /*!
 183 @brief
 184     Increments the \ref api-fund-shared-object "reference count" of
 185     the interrupter \bt_p{interrupter}.
 186
 187 @param[in] interrupter
 188     @parblock
 189     Interrupter of which to increment the reference count.
 190
 191     Can be \c NULL.
 192     @endparblock
 193
 194 @sa bt_interrupter_put_ref() &mdash;
 195     Decrements the reference count of an interrupter.
 196 */
 197 extern void bt_interrupter_get_ref(const bt_interrupter *interrupter);
 198
 199 /*!
 200 @brief
 201     Decrements the \ref api-fund-shared-object "reference count" of
 202     the interrupter \bt_p{interrupter}.
 203
 204 @param[in] interrupter
 205     @parblock
 206     Interrupter of which to decrement the reference count.
 207
 208     Can be \c NULL.
 209     @endparblock
 210
 211 @sa bt_interrupter_get_ref() &mdash;
 212     Increments the reference count of an interrupter.
 213 */
 214 extern void bt_interrupter_put_ref(const bt_interrupter *interrupter);
 215
 216 /*!
 217 @brief
 218     Decrements the reference count of the interrupter
 219     \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
 220
 221 @param _interrupter
 222     @parblock
 223     Interrupter of which to decrement the reference count.
 224
 225     Can contain \c NULL.
 226     @endparblock
 227
 228 @bt_pre_assign_expr{_interrupter}
 229 */
 230 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)  \
 231         do {                                            \
 232                 bt_interrupter_put_ref(_interrupter);   \
 233                 (_interrupter) = NULL;                  \
 234         } while (0)
 235
 236 /*!
 237 @brief
 238     Decrements the reference count of the interrupter \bt_p{_dst}, sets
 239     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 240
 241 This macro effectively moves an interrupter reference from the
 242 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
 243 existing \bt_p{_dst} reference.
 244
 245 @param _dst
 246     @parblock
 247     Destination expression.
 248
 249     Can contain \c NULL.
 250     @endparblock
 251 @param _src
 252     @parblock
 253     Source expression.
 254
 255     Can contain \c NULL.
 256     @endparblock
 257
 258 @bt_pre_assign_expr{_dst}
 259 @bt_pre_assign_expr{_src}
 260 */
 261 #define BT_INTERRUPTER_MOVE_REF(_dst, _src)     \
 262         do {                                    \
 263                 bt_interrupter_put_ref(_dst);   \
 264                 (_dst) = (_src);                \
 265                 (_src) = NULL;                  \
 266         } while (0)
 267
 268 /*! @} */
 269
 270 /*! @} */
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */