doc/api/libbabeltrace2/DoxygenLayout.xml: use `topics` tab

[babeltrace.git] / include / babeltrace2 / graph / message.h

diff --git a/include/babeltrace2/graph/message.h b/include/babeltrace2/graph/message.h
index bc977238c8cb7a0a904ad59f9104fc743be3d504..f634f888fc7bc3bf1a5b249bb054d576a021afb9 100644 (file)
--- a/include/babeltrace2/graph/message.h
+++ b/include/babeltrace2/graph/message.h
@@ -7,6 +7,8 @@
 #ifndef BABELTRACE2_GRAPH_MESSAGE_H
 #define BABELTRACE2_GRAPH_MESSAGE_H
 
+/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
+
 #ifndef __BT_IN_BABELTRACE_H
 # error "Please include <babeltrace2/babeltrace.h> instead."
 #endif
@@ -790,7 +792,7 @@ A message iterator inactivity message has the following property:
 <h1>\anchor api-msg-mip Message Interchange Protocol</h1>
 
 The <em>Message Interchange Protocol</em> (MIP) is the system of rules
-used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
+used by \bt_p_comp and \bt_p_msg_iter to exchange messages within a
 trace processing graph.
 
 The MIP covers everything related to messages and what they contain, as
@@ -804,7 +806,7 @@ For example:
 
 - The maximum
   \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
-  is [0,&nbsp;2<sup>64</sup>&nbsp;-&nbsp;1].
+  is [0,&nbsp;2<sup>64</sup>&nbsp;−&nbsp;1].
 
 - The available message types are stream beginning and end, event,
   packet beginning and end, discarded events and packets, and message
@@ -846,7 +848,7 @@ version as rarely as possible. When it is required, though, it's a
 welcome tool to make the project evolve gracefully.
 
 The Message Interchange Protocol has no dedicated documentation as this
-very message module (and its submodules, like \ref api-tir)
+very message API (and its contained APIs, like \ref api-tir)
 documentation is enough. You can consider that all the
 functions of the message and trace IR objects have an implicit MIP
 version \ref api-fund-pre-post "precondition". When a given
@@ -1023,7 +1025,8 @@ typedef enum bt_message_type {
 
 @bt_pre_not_null{message}
 */
-extern bt_message_type bt_message_get_type(const bt_message *message);
+extern bt_message_type bt_message_get_type(const bt_message *message)
+               __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -1097,7 +1100,7 @@ property values:
 extern
 bt_message *bt_message_stream_beginning_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_stream *stream);
+               const bt_stream *stream) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1122,7 +1125,7 @@ See the \ref api-msg-sb-prop-stream "stream" property.
     \c const version of this function.
 */
 extern bt_stream *bt_message_stream_beginning_borrow_stream(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1132,7 +1135,7 @@ extern bt_stream *bt_message_stream_beginning_borrow_stream(
 See bt_message_stream_beginning_borrow_stream().
 */
 extern const bt_stream *bt_message_stream_beginning_borrow_stream_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1160,7 +1163,7 @@ See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
 */
 extern
 void bt_message_stream_beginning_set_default_clock_snapshot(
-               bt_message *message, uint64_t value);
+               bt_message *message, uint64_t value) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1196,7 +1199,7 @@ See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
 extern bt_message_stream_clock_snapshot_state
 bt_message_stream_beginning_borrow_default_clock_snapshot_const(
                const bt_message *message,
-               const bt_clock_snapshot **clock_snapshot);
+               const bt_clock_snapshot **clock_snapshot) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1228,7 +1231,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -1274,7 +1277,7 @@ property values:
 extern
 bt_message *bt_message_stream_end_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_stream *stream);
+               const bt_stream *stream) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1299,7 +1302,7 @@ See the \ref api-msg-se-prop-stream "stream" property.
     \c const version of this function.
 */
 extern bt_stream *bt_message_stream_end_borrow_stream(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1309,7 +1312,7 @@ extern bt_stream *bt_message_stream_end_borrow_stream(
 See bt_message_stream_end_borrow_stream().
 */
 extern const bt_stream *bt_message_stream_end_borrow_stream_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1337,7 +1340,7 @@ See the \ref api-msg-se-prop-cs "default clock snapshot" property.
 */
 extern
 void bt_message_stream_end_set_default_clock_snapshot(
-               bt_message *message, uint64_t value);
+               bt_message *message, uint64_t value) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1373,7 +1376,7 @@ See the \ref api-msg-se-prop-cs "default clock snapshot" property.
 extern bt_message_stream_clock_snapshot_state
 bt_message_stream_end_borrow_default_clock_snapshot_const(
                const bt_message *message,
-               const bt_clock_snapshot **clock_snapshot);
+               const bt_clock_snapshot **clock_snapshot) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1405,7 +1408,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_stream_end_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -1492,7 +1495,7 @@ extern
 bt_message *bt_message_event_create(
                bt_self_message_iterator *self_message_iterator,
                const bt_event_class *event_class,
-               const bt_stream *stream);
+               const bt_stream *stream) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1576,7 +1579,8 @@ extern
 bt_message *bt_message_event_create_with_default_clock_snapshot(
                bt_self_message_iterator *self_message_iterator,
                const bt_event_class *event_class,
-               const bt_stream *stream, uint64_t clock_snapshot_value);
+               const bt_stream *stream, uint64_t clock_snapshot_value)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1661,7 +1665,7 @@ extern
 bt_message *bt_message_event_create_with_packet(
                bt_self_message_iterator *self_message_iterator,
                const bt_event_class *event_class,
-               const bt_packet *packet);
+               const bt_packet *packet) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1750,7 +1754,8 @@ extern
 bt_message *bt_message_event_create_with_packet_and_default_clock_snapshot(
                bt_self_message_iterator *self_message_iterator,
                const bt_event_class *event_class,
-               const bt_packet *packet, uint64_t clock_snapshot_value);
+               const bt_packet *packet, uint64_t clock_snapshot_value)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1774,8 +1779,8 @@ See the \ref api-msg-ev-prop-ev "event" property.
 @sa bt_message_event_borrow_event_const() &mdash;
     \c const version of this function.
 */
-extern bt_event *bt_message_event_borrow_event(
-               bt_message *message);
+extern bt_event *bt_message_event_borrow_event(bt_message *message)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1785,7 +1790,7 @@ extern bt_event *bt_message_event_borrow_event(
 See bt_message_event_borrow_event().
 */
 extern const bt_event *bt_message_event_borrow_event_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1806,7 +1811,8 @@ See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
     \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
 */
 extern const bt_clock_snapshot *
-bt_message_event_borrow_default_clock_snapshot_const(const bt_message *message);
+bt_message_event_borrow_default_clock_snapshot_const(const bt_message *message)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1839,7 +1845,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_event_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -1907,7 +1913,7 @@ property values:
 extern
 bt_message *bt_message_packet_beginning_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_packet *packet);
+               const bt_packet *packet) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1972,7 +1978,8 @@ property values:
 extern
 bt_message *bt_message_packet_beginning_create_with_default_clock_snapshot(
                bt_self_message_iterator *self_message_iterator,
-               const bt_packet *packet, uint64_t clock_snapshot_value);
+               const bt_packet *packet, uint64_t clock_snapshot_value)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -1997,7 +2004,7 @@ See the \ref api-msg-pb-prop-pkt "packet" property.
     \c const version of this function.
 */
 extern bt_packet *bt_message_packet_beginning_borrow_packet(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2007,7 +2014,7 @@ extern bt_packet *bt_message_packet_beginning_borrow_packet(
 See bt_message_packet_beginning_borrow_packet().
 */
 extern const bt_packet *bt_message_packet_beginning_borrow_packet_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2030,7 +2037,7 @@ See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
 */
 extern const bt_clock_snapshot *
 bt_message_packet_beginning_borrow_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2063,7 +2070,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -2130,7 +2137,7 @@ property values:
 extern
 bt_message *bt_message_packet_end_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_packet *packet);
+               const bt_packet *packet) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2195,7 +2202,8 @@ property values:
 extern
 bt_message *bt_message_packet_end_create_with_default_clock_snapshot(
                bt_self_message_iterator *self_message_iterator,
-               const bt_packet *packet, uint64_t clock_snapshot_value);
+               const bt_packet *packet, uint64_t clock_snapshot_value)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2220,7 +2228,7 @@ See the \ref api-msg-pe-prop-pkt "packet" property.
     \c const version of this function.
 */
 extern bt_packet *bt_message_packet_end_borrow_packet(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2230,7 +2238,7 @@ extern bt_packet *bt_message_packet_end_borrow_packet(
 See bt_message_packet_end_borrow_packet().
 */
 extern const bt_packet *bt_message_packet_end_borrow_packet_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2253,7 +2261,7 @@ See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
 */
 extern const bt_clock_snapshot *
 bt_message_packet_end_borrow_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2286,7 +2294,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_packet_end_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -2355,7 +2363,7 @@ property values:
 */
 extern bt_message *bt_message_discarded_events_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_stream *stream);
+               const bt_stream *stream) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2428,7 +2436,8 @@ extern bt_message *bt_message_discarded_events_create_with_default_clock_snapsho
                bt_self_message_iterator *self_message_iterator,
                const bt_stream *stream,
                uint64_t beginning_clock_snapshot_value,
-               uint64_t end_clock_snapshot_value);
+               uint64_t end_clock_snapshot_value)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2453,7 +2462,7 @@ See the \ref api-msg-disc-ev-prop-stream "stream" property.
     \c const version of this function.
 */
 extern bt_stream *bt_message_discarded_events_borrow_stream(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2463,7 +2472,8 @@ extern bt_stream *bt_message_discarded_events_borrow_stream(
 See bt_message_discarded_events_borrow_stream().
 */
 extern const bt_stream *
-bt_message_discarded_events_borrow_stream_const(const bt_message *message);
+bt_message_discarded_events_borrow_stream_const(const bt_message *message)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2490,7 +2500,7 @@ property.
 */
 extern const bt_clock_snapshot *
 bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2517,7 +2527,7 @@ property.
 */
 extern const bt_clock_snapshot *
 bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2549,7 +2559,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2568,13 +2578,15 @@ property.
 @bt_pre_not_null{message}
 @bt_pre_hot{message}
 @bt_pre_is_disc_ev_msg{message}
+@pre
+    \bt_p{count} > 0
 
 @sa bt_message_discarded_events_get_count() &mdash;
     Returns the number of discarded events of a discarded events
     message.
 */
 extern void bt_message_discarded_events_set_count(bt_message *message,
-               uint64_t count);
+               uint64_t count) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2605,7 +2617,7 @@ property.
     Sets the number of discarded events of a discarded events message.
 */
 extern bt_property_availability bt_message_discarded_events_get_count(
-               const bt_message *message, uint64_t *count);
+               const bt_message *message, uint64_t *count) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -2674,7 +2686,7 @@ property values:
 */
 extern bt_message *bt_message_discarded_packets_create(
                bt_self_message_iterator *self_message_iterator,
-               const bt_stream *stream);
+               const bt_stream *stream) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2746,7 +2758,7 @@ property values:
 extern bt_message *bt_message_discarded_packets_create_with_default_clock_snapshots(
                bt_self_message_iterator *self_message_iterator,
                const bt_stream *stream, uint64_t beginning_clock_snapshot_value,
-               uint64_t end_clock_snapshot_value);
+               uint64_t end_clock_snapshot_value) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2771,7 +2783,7 @@ See the \ref api-msg-disc-ev-prop-stream "stream" property.
     \c const version of this function.
 */
 extern bt_stream *bt_message_discarded_packets_borrow_stream(
-               bt_message *message);
+               bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2781,7 +2793,8 @@ extern bt_stream *bt_message_discarded_packets_borrow_stream(
 See bt_message_discarded_packets_borrow_stream().
 */
 extern const bt_stream *
-bt_message_discarded_packets_borrow_stream_const(const bt_message *message);
+bt_message_discarded_packets_borrow_stream_const(const bt_message *message)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2808,7 +2821,7 @@ property.
 */
 extern const bt_clock_snapshot *
 bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2835,7 +2848,7 @@ property.
 */
 extern const bt_clock_snapshot *
 bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2867,7 +2880,7 @@ bt_stream_class_borrow_default_clock_class_const(
 */
 extern const bt_clock_class *
 bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2886,13 +2899,15 @@ property.
 @bt_pre_not_null{message}
 @bt_pre_hot{message}
 @bt_pre_is_disc_pkt_msg{message}
+@pre
+    \bt_p{count} > 0
 
 @sa bt_message_discarded_packets_get_count() &mdash;
     Returns the number of discarded packets of a discarded packets
     message.
 */
 extern void bt_message_discarded_packets_set_count(bt_message *message,
-               uint64_t count);
+               uint64_t count) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2923,7 +2938,7 @@ property.
     Sets the number of discarded packets of a discarded packets message.
 */
 extern bt_property_availability bt_message_discarded_packets_get_count(
-               const bt_message *message, uint64_t *count);
+               const bt_message *message, uint64_t *count) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -2975,7 +2990,7 @@ extern
 bt_message *bt_message_message_iterator_inactivity_create(
                bt_self_message_iterator *self_message_iterator,
                const bt_clock_class *clock_class,
-               uint64_t clock_snapshot_value);
+               uint64_t clock_snapshot_value) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -2995,7 +3010,7 @@ See the \ref api-msg-inac-prop-cs "clock snapshot" property.
 */
 extern const bt_clock_snapshot *
 bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
-               const bt_message *message);
+               const bt_message *message) __BT_NOEXCEPT;
 
 /*! @} */
 
@@ -3019,7 +3034,7 @@ bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
 @sa bt_message_put_ref() &mdash;
     Decrements the reference count of a message.
 */
-extern void bt_message_get_ref(const bt_message *message);
+extern void bt_message_get_ref(const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -3036,7 +3051,7 @@ extern void bt_message_get_ref(const bt_message *message);
 @sa bt_message_get_ref() &mdash;
     Increments the reference count of a message.
 */
-extern void bt_message_put_ref(const bt_message *message);
+extern void bt_message_put_ref(const bt_message *message) __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -3182,7 +3197,8 @@ component descriptors of \bt_p{component_descriptors}, it returns
 extern bt_get_greatest_operative_mip_version_status
 bt_get_greatest_operative_mip_version(
                const bt_component_descriptor_set *component_descriptors,
-               bt_logging_level logging_level, uint64_t *mip_version);
+               bt_logging_level logging_level, uint64_t *mip_version)
+               __BT_NOEXCEPT;
 
 /*!
 @brief
@@ -3195,7 +3211,7 @@ As of \bt_name_version_min_maj, this function returns
 @returns
     Maximal available MIP version (\bt_max_mip_version).
 */
-extern uint64_t bt_get_maximal_mip_version(void);
+extern uint64_t bt_get_maximal_mip_version(void) __BT_NOEXCEPT;
 
 /*! @} */