X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Finterrupter.h;h=00b9512fba6a046ad4c75b9e1e3542661fdf2158;hb=0235b0db7de5bcacdb3650c92461f2ce5eb2143d;hp=953775329165435d50f37718340c2d4642d8e9a6;hpb=b70d57a123c4e4a208b988539a7eb8fceb2b63a7;p=babeltrace.git diff --git a/include/babeltrace2/graph/interrupter.h b/include/babeltrace2/graph/interrupter.h index 95377532..00b9512f 100644 --- a/include/babeltrace2/graph/interrupter.h +++ b/include/babeltrace2/graph/interrupter.h @@ -1,28 +1,12 @@ -#ifndef BABELTRACE2_GRAPH_INTERRUPTER_H -#define BABELTRACE2_GRAPH_INTERRUPTER_H - /* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. + * SPDX-License-Identifier: MIT * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. + * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation */ +#ifndef BABELTRACE2_GRAPH_INTERRUPTER_H +#define BABELTRACE2_GRAPH_INTERRUPTER_H + #ifndef __BT_IN_BABELTRACE_H # error "Please include instead." #endif @@ -33,12 +17,258 @@ extern "C" { #endif +/*! +@defgroup api-intr Interrupter +@ingroup api-graph + +@brief + Interrupter. + +An interrupter 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