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 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-intr Interrupter
  24 @ingroup api-graph
  25
  26 @brief
  27     Interrupter.
  28
  29 An <strong><em>interrupter</em></strong> is a simple object which has
  30 a single boolean state: set or not set.
  31
  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().
  39
  40 To interrupt a running trace processing graph or query:
  41
  42 -# Create an interrupter with bt_interrupter_create().
  43
  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().
  48
  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().
  52
  53 -# Run the graph with bt_graph_run() or perform the query with
  54    bt_query_executor_query().
  55
  56 -# From a signal handler or another thread, call bt_interrupter_set() to
  57    set the shared interrupter.
  58
  59 Eventually, the trace processing graph or query thread checks if it's
  60 interrupted and stops processing, usually returning a status code which
  61 ends with \c _AGAIN.
  62
  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.
  69
  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.
  74
  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().
  78
  79 The type of an interrupter is #bt_interrupter.
  80 */
  81
  82 /*! @{ */
  83
  84 /*!
  85 @name Type
  86 @{
  87
  88 @typedef struct bt_interrupter bt_interrupter;
  89
  90 @brief
  91     Interrupter.
  92
  93 @}
  94 */
  95
  96 /*!
  97 @name Creation
  98 @{
  99 */
 100
 101 /*!
 102 @brief
 103     Creates a default interrupter.
 104
 105 On success, the returned interrupter is \em not set
 106 (bt_interrupter_is_set() returns #BT_FALSE).
 107
 108 @returns
 109     New interrupter reference, or \c NULL on memory error.
 110 */
 111 extern bt_interrupter *bt_interrupter_create(void);
 112
 113 /*! @} */
 114
 115 /*!
 116 @name State
 117 @{
 118 */
 119
 120 /*!
 121 @brief
 122     Sets the interrupter \bt_p{interrupter}.
 123
 124 After you call this function, bt_interrupter_is_set() returns
 125 #BT_TRUE.
 126
 127 @param[in] interrupter
 128     Interrupter to set.
 129
 130 @bt_pre_not_null{interrupter}
 131
 132 @sa bt_interrupter_reset() &mdash;
 133     Resets an interrupter.
 134 @sa bt_interrupter_is_set() &mdash;
 135     Returns whether or not an interrupter is set.
 136 */
 137 extern void bt_interrupter_set(bt_interrupter *interrupter);
 138
 139 /*!
 140 @brief
 141     Resets the interrupter \bt_p{interrupter}.
 142
 143 After you call this function, bt_interrupter_is_set() returns
 144 #BT_FALSE.
 145
 146 @param[in] interrupter
 147     Interrupter to reset.
 148
 149 @bt_pre_not_null{interrupter}
 150
 151 @sa bt_interrupter_set() &mdash;
 152     Sets an interrupter.
 153 @sa bt_interrupter_is_set() &mdash;
 154     Returns whether or not an interrupter is set.
 155 */
 156 extern void bt_interrupter_reset(bt_interrupter *interrupter);
 157
 158 /*!
 159 @brief
 160     Returns whether or not the interrupter \bt_p{interrupter} is set.
 161
 162 @param[in] interrupter
 163     Interrupter to reset.
 164
 165 @returns
 166     #BT_TRUE if \bt_p{interrupter} is set.
 167
 168 @bt_pre_not_null{interrupter}
 169
 170 @sa bt_interrupter_set() &mdash;
 171     Sets an interrupter.
 172 @sa bt_interrupter_reset() &mdash;
 173     Resets an interrupter.
 174 */
 175 extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter);
 176
 177 /*! @} */
 178
 179 /*!
 180 @name Reference count
 181 @{
 182 */
 183
 184 /*!
 185 @brief
 186     Increments the \ref api-fund-shared-object "reference count" of
 187     the interrupter \bt_p{interrupter}.
 188
 189 @param[in] interrupter
 190     @parblock
 191     Interrupter of which to increment the reference count.
 192
 193     Can be \c NULL.
 194     @endparblock
 195
 196 @sa bt_interrupter_put_ref() &mdash;
 197     Decrements the reference count of an interrupter.
 198 */
 199 extern void bt_interrupter_get_ref(const bt_interrupter *interrupter);
 200
 201 /*!
 202 @brief
 203     Decrements the \ref api-fund-shared-object "reference count" of
 204     the interrupter \bt_p{interrupter}.
 205
 206 @param[in] interrupter
 207     @parblock
 208     Interrupter of which to decrement the reference count.
 209
 210     Can be \c NULL.
 211     @endparblock
 212
 213 @sa bt_interrupter_get_ref() &mdash;
 214     Increments the reference count of an interrupter.
 215 */
 216 extern void bt_interrupter_put_ref(const bt_interrupter *interrupter);
 217
 218 /*!
 219 @brief
 220     Decrements the reference count of the interrupter
 221     \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
 222
 223 @param _interrupter
 224     @parblock
 225     Interrupter of which to decrement the reference count.
 226
 227     Can contain \c NULL.
 228     @endparblock
 229
 230 @bt_pre_assign_expr{_interrupter}
 231 */
 232 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)  \
 233         do {                                            \
 234                 bt_interrupter_put_ref(_interrupter);   \
 235                 (_interrupter) = NULL;                  \
 236         } while (0)
 237
 238 /*!
 239 @brief
 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.
 242
 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.
 246
 247 @param _dst
 248     @parblock
 249     Destination expression.
 250
 251     Can contain \c NULL.
 252     @endparblock
 253 @param _src
 254     @parblock
 255     Source expression.
 256
 257     Can contain \c NULL.
 258     @endparblock
 259
 260 @bt_pre_assign_expr{_dst}
 261 @bt_pre_assign_expr{_src}
 262 */
 263 #define BT_INTERRUPTER_MOVE_REF(_dst, _src)     \
 264         do {                                    \
 265                 bt_interrupter_put_ref(_dst);   \
 266                 (_dst) = (_src);                \
 267                 (_src) = NULL;                  \
 268         } while (0)
 269
 270 /*! @} */
 271
 272 /*! @} */
 273
 274 #ifdef __cplusplus
 275 }
 276 #endif
 277
 278 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */