include/babeltrace2/graph/interrupter.h

   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
  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 */
 125 extern bt_interrupter *bt_interrupter_create(void);
 126
 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() &mdash;
 147     Resets an interrupter.
 148 @sa bt_interrupter_is_set() &mdash;
 149     Returns whether or not an interrupter is set.
 150 */
 151 extern void bt_interrupter_set(bt_interrupter *interrupter);
 152
 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() &mdash;
 166     Sets an interrupter.
 167 @sa bt_interrupter_is_set() &mdash;
 168     Returns whether or not an interrupter is set.
 169 */
 170 extern void bt_interrupter_reset(bt_interrupter *interrupter);
 171
 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() &mdash;
 185     Sets an interrupter.
 186 @sa bt_interrupter_reset() &mdash;
 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() &mdash;
 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() &mdash;
 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
 288 #ifdef __cplusplus
 289 }
 290 #endif
 291
 292 #endif /* BABELTRACE2_GRAPH_INTERRUPTER_H */