X-Git-Url: https://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fmessage-iterator.h;h=cda5040ae0c6fa819d3fd50488f6f076b18ef423;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hp=228b40d1ab15b70d81f27edb96b042776a90be62;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9;p=babeltrace.git diff --git a/include/babeltrace2/graph/message-iterator.h b/include/babeltrace2/graph/message-iterator.h index 228b40d1..cda5040a 100644 --- a/include/babeltrace2/graph/message-iterator.h +++ b/include/babeltrace2/graph/message-iterator.h @@ -31,125 +31,865 @@ extern "C" { #endif +/*! +@defgroup api-msg-iter Message iterator +@ingroup api-comp-cls-dev + +@brief + Iterator of a \bt_msg sequence. + +A message iterator iterates a sequence of +\bt_p_msg. + +A message iterator is the \bt_name mechanism for the \bt_p_comp of a +trace processing \bt_graph to exchange information. This information +takes the form of a sequence of individual messages which contain +trace data (\bt_p_ev, for example). + +A message iterator is a \bt_msg_iter_cls instance. Because a message +iterator class is part of a \bt_src_comp_cls or \bt_flt_comp_cls, a +message iterator is part of a \bt_src_comp or \bt_flt_comp. Borrow +a message iterator's component with +bt_message_iterator_borrow_component(). + +A message iterator is a \ref api-fund-shared-object "shared object": get +a new reference with bt_component_get_ref() and put an existing +reference with bt_component_put_ref(). + +The type of a message iterator is #bt_message_iterator. + +There are two contexts from which you can create a message iterator: + +
bt_port_is_connected(port)
returns #BT_TRUE.
+@bt_pre_not_null{message_iterator}
+
+@sa bt_message_iterator_create_from_sink_component() —
+ Creates a message iterator from a \bt_sink_comp.
+*/
+extern bt_message_iterator_create_from_message_iterator_status
+bt_message_iterator_create_from_message_iterator(
+ bt_self_message_iterator *self_message_iterator,
+ bt_self_component_port_input *port,
+ bt_message_iterator **message_iterator);
+
+/*!
+@brief
+ Status code for bt_message_iterator_create_from_sink_component().
+*/
+typedef enum bt_message_iterator_create_from_sink_component_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_create_from_sink_component_status;
+
+/*!
+@brief
+ Creates a message iterator on the \bt_iport \bt_p{port} from the
+ \bt_sink_comp \bt_p{self_component_sink}, and sets
+ \bt_p{*message_iterator} to the resulting message iterator.
+
+On success, the message iterator's position is at the beginning
+of its \ref api-msg-seq "message sequence".
+
+@param[in] self_component_sink
+ Sink component from which to create the message iterator.
+@param[in] port
+ Input port on which to create the message iterator.
+@param[out] message_iterator
+ On success, \bt_p{*message_iterator} is a new
+ message iterator reference.
+
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
+ Other error, for example, the created message iterator's
+ \ref api-msg-iter-cls-meth-init "initialization method" failed.
+
+@bt_pre_not_null{self_component_sink}
+@bt_pre_not_null{port}
+@pre
+ bt_port_is_connected(port)
returns #BT_TRUE.
+@bt_pre_not_null{message_iterator}
+
+@sa bt_message_iterator_create_from_message_iterator() —
+ Creates a message iterator from another message iterator.
+*/
+extern bt_message_iterator_create_from_sink_component_status
+bt_message_iterator_create_from_sink_component(
+ bt_self_component_sink *self_component_sink,
+ bt_self_component_port_input *port,
+ bt_message_iterator **message_iterator);
+
+/*! @} */
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+ Borrows the \bt_comp which provides the \bt_msg_iter
+ \bt_p{message_iterator}.
+
+@param[in] message_iterator
+ Message iterator from which to borrow the component which provides
+ it.
+
+@returns
+ Component which provides \bt_p{message_iterator}.
+
+@bt_pre_not_null{message_iterator}
+*/
+extern bt_component *
+bt_message_iterator_borrow_component(
+ bt_message_iterator *message_iterator);
+
+/*! @} */
+
+/*!
+@name "Next" operation (get next messages)
+@{
+*/
+
+/*!
+@brief
+ Status code for bt_message_iterator_next().
+*/
typedef enum bt_message_iterator_next_status {
+ /*!
+ @brief
+ Success.
+ */
BT_MESSAGE_ITERATOR_NEXT_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ End of iteration.
+ */
BT_MESSAGE_ITERATOR_NEXT_STATUS_END = __BT_FUNC_STATUS_END,
+
+ /*!
+ @brief
+ Try again.
+ */
BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_message_iterator_next_status;
-typedef enum bt_message_iterator_seek_beginning_status {
- BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_seek_beginning_status;
+/*!
+@brief
+ Returns the next \bt_p_msg of the message iterator
+ \bt_p{message_iterator} into the \bt_p{*messages} array of size
+ \bt_p{*count}, effectively advancing \bt_p{message_iterator}.
-typedef enum bt_message_iterator_seek_ns_from_origin_status {
- BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_seek_ns_from_origin_status;
+See \ref api-msg-iter-op-next "this operation's documentation".
+
+On success, the message iterator's position is advanced by \bt_p{*count}
+messages.
+
+@param[in] message_iterator
+ Message iterator from which to get the next messages.
+@param[out] messages
+ @parblock
+ On success, \bt_p{*messages} is an array containing
+ the next messages of \bt_p{message_iterator} as its first elements.
+
+ \bt_p{*count} is the number of messages in \bt_p{*messages}.
+ The library allocates and manages this array, but until you
+ perform another \ref api-msg-iter-ops "operation" on
+ \bt_p{message_iterator}, you are free to modify it. For example,
+ you can set its elements to \c NULL if your use case needs it.
+
+ You own the references of the messages this array contains. In
+ other words, you must put them with bt_message_put_ref() or move
+ them to another message array (from a
+ \link api-msg-iter-cls-meth-next "next" method\endlink)
+ before you perform another operation on \bt_p{message_iterator} or
+ before \bt_p{message_iterator} is destroyed.
+ @endparblock
+@param[out] count
+ On success, \bt_p{*count} is the number of messages
+ in \bt_p{*messages}.
+
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
+ End of iteration.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{messages}
+@bt_pre_not_null{count}
+
+@post
+ On success, \bt_p{*count} ⥠1.
+*/
+extern bt_message_iterator_next_status
+bt_message_iterator_next(bt_message_iterator *message_iterator,
+ bt_message_array_const *messages, uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Seeking
+@{
+*/
+
+/*!
+@brief
+ Status code for bt_message_iterator_can_seek_beginning().
+*/
typedef enum bt_message_iterator_can_seek_beginning_status {
+ /*!
+ @brief
+ Success.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_message_iterator_can_seek_beginning_status;
+/*!
+@brief
+ Returns whether or not the message iterator \bt_p{message_iterator}
+ can currently seek its beginning (first \bt_msg).
+
+See the \link api-msg-iter-op-seek-beg "seek beginning"
+operation\endlink.
+
+Make sure to call this function, without performing any other
+\ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
+call bt_message_iterator_seek_beginning().
+
+@param[in] message_iterator
+ Message iterator from which to to get whether or not it can seek
+ its beginning.
+@param[out] can_seek_beginning
+ On success, \bt_p{*can_seek_beginning} is #BT_TRUE
+ if \bt_p{message_iterator} can seek its beginning.
+
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{can_seek_beginning}
+
+@sa bt_message_iterator_seek_beginning() —
+ Makes a message iterator seek its beginning.
+*/
+extern bt_message_iterator_can_seek_beginning_status
+bt_message_iterator_can_seek_beginning(
+ bt_message_iterator *message_iterator,
+ bt_bool *can_seek_beginning);
+
+/*!
+@brief
+ Status code for bt_message_iterator_seek_beginning().
+*/
+typedef enum bt_message_iterator_seek_beginning_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_seek_beginning_status;
+
+/*!
+@brief
+ Makes the message iterator \bt_p{message_iterator} seek its
+ beginning (first \bt_msg).
+
+See \ref api-msg-iter-op-seek-beg "this operation's documentation".
+
+Make sure to call bt_message_iterator_can_seek_beginning(),
+without performing any other \ref api-msg-iter-ops "operation" on
+\bt_p{message_iterator}, before you call this function.
+
+@param[in] message_iterator
+ Message iterator to seek to its beginning.
+
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
+ Other error.
+
+@bt_pre_not_null{message_iterator}
+@pre
+ bt_message_iterator_can_seek_beginning(message_iterator)
+ returns #BT_TRUE.
+
+@sa bt_message_iterator_can_seek_beginning() —
+ Returns whether or not a message iterator can currently seek its
+ beginning.
+*/
+extern bt_message_iterator_seek_beginning_status
+bt_message_iterator_seek_beginning(
+ bt_message_iterator *message_iterator);
+
+/*!
+@brief
+ Status code for bt_message_iterator_can_seek_ns_from_origin().
+*/
typedef enum bt_message_iterator_can_seek_ns_from_origin_status {
+ /*!
+ @brief
+ Success.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
- BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+
+ /*!
+ @brief
+ Out of memory.
+ */
BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
} bt_message_iterator_can_seek_ns_from_origin_status;
-typedef enum bt_message_iterator_create_from_message_iterator_status {
- BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_create_from_message_iterator_status;
+/*!
+@brief
+ Returns whether or not the message iterator \bt_p{message_iterator}
+ can currently seek a \bt_msg occuring at or after
+ \bt_p{ns_from_origin} nanoseconds from its
+ \ref api-tir-clock-cls-origin "clock class origin".
-typedef enum bt_message_iterator_create_from_sink_component_status {
- BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK = __BT_FUNC_STATUS_OK,
- BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
- BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_create_from_sink_component_status;
+See the \link api-msg-iter-op-seek-ns "seek ns from origin"
+operation\endlink.
-static inline
-bt_message_iterator *
-bt_message_iterator_as_message_iterator(
- bt_message_iterator *iterator)
-{
- return __BT_UPCAST(bt_message_iterator, iterator);
-}
+Make sure to call this function, without performing any other
+\ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
+call bt_message_iterator_seek_ns_from_origin().
-extern bt_message_iterator_create_from_message_iterator_status
-bt_message_iterator_create_from_message_iterator(
- bt_self_message_iterator *self_msg_iter,
- bt_self_component_port_input *input_port,
- bt_message_iterator **message_iterator);
+@param[in] message_iterator
+ Message iterator from which to to get whether or not it can seek
+ its beginning.
+@param[in] ns_from_origin
+ Requested time point to seek.
+@param[out] can_seek_ns_from_origin
+ On success, \bt_p{*can_seek_ns_from_origin} is
+ #BT_TRUE if \bt_p{message_iterator} can seek a message occuring at
+ or after \bt_p{ns_from_origin} nanoseconds from its clock class
+ origin.
-extern bt_message_iterator_create_from_sink_component_status
-bt_message_iterator_create_from_sink_component(
- bt_self_component_sink *self_comp,
- bt_self_component_port_input *input_port,
- bt_message_iterator **message_iterator);
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
+ Other error.
-extern bt_component *
-bt_message_iterator_borrow_component(
- bt_message_iterator *iterator);
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{can_seek_ns_from_origin}
-extern bt_message_iterator_next_status
-bt_message_iterator_next(
- bt_message_iterator *iterator,
- bt_message_array_const *msgs, uint64_t *count);
+@sa bt_message_iterator_seek_ns_from_origin() —
+ Makes a message iterator seek a message occuring at or after
+ a given time from its clock class origin.
+*/
extern bt_message_iterator_can_seek_ns_from_origin_status
bt_message_iterator_can_seek_ns_from_origin(
- bt_message_iterator *iterator,
- int64_t ns_from_origin, bt_bool *can_seek);
+ bt_message_iterator *message_iterator,
+ int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
-extern bt_message_iterator_can_seek_beginning_status
-bt_message_iterator_can_seek_beginning(
- bt_message_iterator *iterator,
- bt_bool *can_seek);
+/*!
+@brief
+ Status code for bt_message_iterator_seek_ns_from_origin().
+*/
+typedef enum bt_message_iterator_seek_ns_from_origin_status {
+ /*!
+ @brief
+ Success.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK,
+
+ /*!
+ @brief
+ Try again.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
+
+ /*!
+ @brief
+ Out of memory.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+ /*!
+ @brief
+ Other error.
+ */
+ BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_seek_ns_from_origin_status;
+
+/*!
+@brief
+ Makes the message iterator \bt_p{message_iterator} seek a \bt_msg
+ occuring at or after \bt_p{ns_from_origin} nanoseconds from its
+ \ref api-tir-clock-cls-origin "clock class origin".
+
+See \ref api-msg-iter-op-seek-ns "this operation's documentation".
+
+Make sure to call bt_message_iterator_can_seek_ns_from_origin(),
+without performing any other \ref api-msg-iter-ops "operation" on
+\bt_p{message_iterator}, before you call this function.
+
+@param[in] message_iterator
+ Message iterator to seek to a message occuring at or after
+ \bt_p{ns_from_origin} nanoseconds from its clock class origin.
+@param[in] ns_from_origin
+ Time point to seek.
+
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
+ Success.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
+ Try again.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
+ Other error.
+@bt_pre_not_null{message_iterator}
+@pre
+ bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin)
+ returns #BT_TRUE.
+
+@sa bt_message_iterator_can_seek_ns_from_origin() —
+ Returns whether or not a message iterator can currently seek a
+ message occuring at or after a given time from its clock class
+ origin.
+*/
extern bt_message_iterator_seek_ns_from_origin_status
bt_message_iterator_seek_ns_from_origin(
- bt_message_iterator *iterator,
+ bt_message_iterator *message_iterator,
int64_t ns_from_origin);
-extern bt_message_iterator_seek_beginning_status
-bt_message_iterator_seek_beginning(
- bt_message_iterator *iterator);
+/*! @} */
+
+/*!
+@name Configuration
+@{
+*/
+
+/*!
+@brief
+ Returns whether or not the message iterator \bt_p{message_iterator}
+ can seek forward.
+
+A message iterator can seek forward if all the \bt_p_msg of its
+message sequence have some \bt_cs.
+
+@param[in] message_iterator
+ Message iterator of which to get whether or not it can seek forward.
+@returns
+ #BT_TRUE if \bt_p{message_iterator} can seek forward.
+
+@sa bt_self_message_iterator_configuration_set_can_seek_forward() —
+ Sets whether or not a message iterator can seek forward.
+*/
extern bt_bool
bt_message_iterator_can_seek_forward(
- bt_message_iterator *iterator);
+ bt_message_iterator *message_iterator);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+ Increments the \ref api-fund-shared-object "reference count" of
+ the message iterator \bt_p{message_iterator}.
+@param[in] message_iterator
+ @parblock
+ Message iterator of which to increment the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_message_iterator_put_ref() —
+ Decrements the reference count of a message iterator.
+*/
extern void bt_message_iterator_get_ref(
const bt_message_iterator *message_iterator);
+/*!
+@brief
+ Decrements the \ref api-fund-shared-object "reference count" of
+ the message iterator \bt_p{message_iterator}.
+
+@param[in] message_iterator
+ @parblock
+ Message iterator of which to decrement the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_message_iterator_get_ref() —
+ Increments the reference count of a message iterator.
+*/
extern void bt_message_iterator_put_ref(
const bt_message_iterator *message_iterator);
-#define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_var) \
+/*!
+@brief
+ Decrements the reference count of the message iterator
+ \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
+ to \c NULL.
+
+@param _message_iterator
+ @parblock
+ Message iterator of which to decrement the reference count.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_message_iterator}
+*/
+#define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator) \
do { \
- bt_message_iterator_put_ref(_var); \
- (_var) = NULL; \
+ bt_message_iterator_put_ref(_message_iterator); \
+ (_message_iterator) = NULL; \
} while (0)
-#define BT_MESSAGE_ITERATOR_MOVE_REF(_var_dst, _var_src) \
- do { \
- bt_message_iterator_put_ref(_var_dst); \
- (_var_dst) = (_var_src); \
- (_var_src) = NULL; \
+/*!
+@brief
+ Decrements the reference count of the message iterator \bt_p{_dst},
+ sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+ \c NULL.
+
+This macro effectively moves a message iterator 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_MESSAGE_ITERATOR_MOVE_REF(_dst, _src) \
+ do { \
+ bt_message_iterator_put_ref(_dst); \
+ (_dst) = (_src); \
+ (_src) = NULL; \
} while (0)
+/*! @} */
+
+/*! @} */
+
#ifdef __cplusplus
}
#endif