X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fself-message-iterator.h;h=452f33a9dc540a40c60e0b9aa1e25857f5ca709a;hp=0ff3c0d3eab235b8a435a2f9bd0248ff15a27663;hb=0235b0db7de5bcacdb3650c92461f2ce5eb2143d;hpb=3fadfbc0c91f82c46bd36e6e0657ea93570c9db1 diff --git a/include/babeltrace2/graph/self-message-iterator.h b/include/babeltrace2/graph/self-message-iterator.h index 0ff3c0d3..452f33a9 100644 --- a/include/babeltrace2/graph/self-message-iterator.h +++ b/include/babeltrace2/graph/self-message-iterator.h @@ -1,63 +1,232 @@ -#ifndef BABELTRACE_GRAPH_SELF_MESSAGE_ITERATOR_H -#define BABELTRACE_GRAPH_SELF_MESSAGE_ITERATOR_H - /* - * Copyright 2017-2018 Philippe Proulx - * - * 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: + * SPDX-License-Identifier: MIT * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * 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 */ -/* For BT_MESSAGE_ITERATOR_STATUS_* */ -#include +#ifndef BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H +#define BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif -/* For bt_self_component, bt_self_message_iterator, bt_self_port_output */ #include #ifdef __cplusplus extern "C" { #endif -typedef enum bt_self_message_iterator_status { - BT_SELF_MESSAGE_ITERATOR_STATUS_OK = BT_MESSAGE_ITERATOR_STATUS_OK, - BT_SELF_MESSAGE_ITERATOR_STATUS_END = BT_MESSAGE_ITERATOR_STATUS_END, - BT_SELF_MESSAGE_ITERATOR_STATUS_AGAIN = BT_MESSAGE_ITERATOR_STATUS_AGAIN, - BT_SELF_MESSAGE_ITERATOR_STATUS_ERROR = BT_MESSAGE_ITERATOR_STATUS_ERROR, - BT_SELF_MESSAGE_ITERATOR_STATUS_NOMEM = BT_MESSAGE_ITERATOR_STATUS_NOMEM, -} bt_self_message_iterator_status; +/*! +@defgroup api-self-msg-iter Self message iterator +@ingroup api-msg-iter-cls + +@brief + Private view of a \bt_msg_iter for methods. + +The #bt_self_message_iterator type is a private view of a \bt_msg_iter +from within a \bt_msg_iter_cls method. + +Borrow the \bt_comp which provides a message iterator with +bt_self_message_iterator_borrow_component(). + +Borrow the \bt_oport on which a message iterator operates with +bt_self_message_iterator_borrow_port(). + +Set and get user data attached to a message iterator with +bt_self_message_iterator_set_data() and +bt_self_message_iterator_get_data(). + +Check whether or not a message iterator is interrupted with +bt_self_message_iterator_is_interrupted(). + +Set whether or not a message iterator can seek forward with +bt_self_message_iterator_configuration_set_can_seek_forward(). +*/ + +/*! @{ */ + +/*! +@name Types +@{ +@typedef struct bt_self_message_iterator bt_self_message_iterator; + +@brief + Self \bt_msg_iter. + +@typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration; + +@brief + Self \bt_msg_iter configuration. + +@} +*/ + +/*! +@name Component access +@{ +*/ + +/*! +@brief + Borrows the \bt_comp which provides the \bt_msg_iter + \bt_p{self_message_iterator}. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + Component which provides \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} +*/ extern bt_self_component * bt_self_message_iterator_borrow_component( - bt_self_message_iterator *message_iterator); + bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name Output port access +@{ +*/ + +/*! +@brief + Borrows the \bt_oport on which the \bt_msg_iter + \bt_p{self_message_iterator} operates. + +@param[in] self_message_iterator + Message iterator instance. -extern bt_self_port_output * +@returns + Output port on which \bt_p{self_message_iterator} operates. + +@bt_pre_not_null{self_message_iterator} +*/ +extern bt_self_component_port_output * bt_self_message_iterator_borrow_port( - bt_self_message_iterator *message_iterator); + bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name User data +@{ +*/ + +/*! +@brief + Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator} + to \bt_p{data}. +@param[in] self_message_iterator + Message iterator instance. +@param[in] user_data + New user data of \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} + +@sa bt_self_message_iterator_get_data() — + Returns the user data of a message iterator. +*/ extern void bt_self_message_iterator_set_data( - bt_self_message_iterator *message_iterator, + bt_self_message_iterator *self_message_iterator, void *user_data); -extern void *bt_self_message_iterator_get_data( - const bt_self_message_iterator *message_iterator); +/*! +@brief + Returns the user data of the \bt_msg_iter + \bt_p{self_message_iterator}. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + User data of \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} + +@sa bt_self_message_iterator_set_data() — + Sets the user data of a message iterator. +*/ +extern +void *bt_self_message_iterator_get_data( + const bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name Interruption query +@{ +*/ + +/*! +@brief + Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator} + is interrupted, that is, whether or not any of its \bt_p_intr + is set. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its + interrupters is set). + +@bt_pre_not_null{self_message_iterator} + +@sa bt_graph_borrow_default_interrupter() — + Borrows a trace processing graph's default interrupter. +@sa bt_graph_add_interrupter() — + Adds an interrupter to a graph. +*/ +extern bt_bool bt_self_message_iterator_is_interrupted( + const bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name Configuration +@{ +*/ + +/*! +@brief + Sets whether or not the \bt_msg_iter of which the configuration + is \bt_p{configuration} can seek forward. + +A message iterator can seek forward if all the \bt_p_msg of its +message sequence have some \bt_cs. + +@attention + You can only call this function during the execution of a + message iterator's + \ref api-msg-iter-cls-meth-init "initialization method". + +@param[in] configuration + Configuration of the message iterator of which to set whether or + not it can seek forward. +@param[in] can_seek_forward + #BT_TRUE to make the message iterator of which the configuration is + \bt_p{configuration} forward-seekable. + +@bt_pre_not_null{configuration} + +@sa bt_message_iterator_can_seek_forward() — + Returns whether or not a message iterator can seek forward. +*/ +extern void bt_self_message_iterator_configuration_set_can_seek_forward( + bt_self_message_iterator_configuration *configuration, + bt_bool can_seek_forward); + +/*! @} */ + +/*! @} */ #ifdef __cplusplus } #endif -#endif /* BABELTRACE_GRAPH_SELF_MESSAGE_ITERATOR_H */ +#endif /* BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H */