X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fself-message-iterator.h;h=452f33a9dc540a40c60e0b9aa1e25857f5ca709a;hp=025eb278a8dfb311e40f3196b467051f7f63d6d1;hb=0235b0db7de5bcacdb3650c92461f2ce5eb2143d;hpb=9b4f9b425f2efce9a6ccc25f7ae062ebc1116a7d diff --git a/include/babeltrace2/graph/self-message-iterator.h b/include/babeltrace2/graph/self-message-iterator.h index 025eb278..452f33a9 100644 --- a/include/babeltrace2/graph/self-message-iterator.h +++ b/include/babeltrace2/graph/self-message-iterator.h @@ -1,28 +1,12 @@ -#ifndef BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H -#define BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_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: + * 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 */ +#ifndef BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H +#define BABELTRACE2_GRAPH_SELF_MESSAGE_ITERATOR_H + #ifndef __BT_IN_BABELTRACE_H # error "Please include instead." #endif @@ -33,23 +17,213 @@ extern "C" { #endif -extern bt_bool bt_self_message_iterator_is_interrupted( - const bt_self_message_iterator *message_iterator); +/*! +@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. -extern bt_self_port_output * +@param[in] self_message_iterator + Message iterator instance. + +@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 }