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) __BT_NOEXCEPT;
 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) __BT_NOEXCEPT;
 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) __BT_NOEXCEPT;
 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                 __BT_NOEXCEPT;
 177
 178 /*! @} */
 179
 180 /*!
 181 @name Reference count
 182 @{
 183 */
 184
 185 /*!
 186 @brief
 187     Increments the \ref api-fund-shared-object "reference count" of
 188     the interrupter \bt_p{interrupter}.
 189
 190 @param[in] interrupter
 191     @parblock
 192     Interrupter of which to increment the reference count.
 193
 194     Can be \c NULL.
 195     @endparblock
 196
 197 @sa bt_interrupter_put_ref() &mdash;
 198     Decrements the reference count of an interrupter.
 199 */
 200 extern void bt_interrupter_get_ref(const bt_interrupter *interrupter)
 201                 __BT_NOEXCEPT;
 202
 203 /*!
 204 @brief
 205     Decrements the \ref api-fund-shared-object "reference count" of
 206     the interrupter \bt_p{interrupter}.
 207
 208 @param[in] interrupter
 209     @parblock
 210     Interrupter of which to decrement the reference count.
 211
 212     Can be \c NULL.
 213     @endparblock
 214
 215 @sa bt_interrupter_get_ref() &mdash;
 216     Increments the reference count of an interrupter.
 217 */
 218 extern void bt_interrupter_put_ref(const bt_interrupter *interrupter)
 219                 __BT_NOEXCEPT;
 220
 221 /*!
 222 @brief
 223     Decrements the reference count of the interrupter
 224     \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
 225
 226 @param _interrupter
 227     @parblock
 228     Interrupter of which to decrement the reference count.
 229
 230     Can contain \c NULL.
 231     @endparblock
 232
 233 @bt_pre_assign_expr{_interrupter}
 234 */
 235 #define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)  \
 236         do {                                            \
 237                 bt_interrupter_put_ref(_interrupter);   \
 238                 (_interrupter) = NULL;                  \
 239         } while (0)
 240
 241 /*!
 242 @brief
 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.
 245
 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.
 249
 250 @param _dst
 251     @parblock
 252     Destination expression.
 253
 254     Can contain \c NULL.
 255     @endparblock
 256 @param _src
 257     @parblock
 258     Source expression.
 259
 260     Can contain \c NULL.
 261     @endparblock
 262
 263 @bt_pre_assign_expr{_dst}
 264 @bt_pre_assign_expr{_src}
 265 */
 266 #define BT_INTERRUPTER_MOVE_REF(_dst, _src)     \
 267         do {                                    \
 268                 bt_interrupter_put_ref(_dst);   \
 269                 (_dst) = (_src);                \
 270                 (_src) = NULL;                  \
 271         } while (0)
 272
 273 /*! @} */
 274
 275 /*! @} */
 276
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */