X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;ds=sidebyside;f=include%2Fbabeltrace2%2Ftrace-ir%2Fpacket.h;h=52d110ee1372d893eb1ee1c91fccc4362771ef09;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hp=fbe5ed049c3f720c0879c6a4516a1a1fb18f967b;hpb=bbb7b5f044dc06e50eaa34ed3a880b34e1e7ebb8;p=babeltrace.git diff --git a/include/babeltrace2/trace-ir/packet.h b/include/babeltrace2/trace-ir/packet.h index fbe5ed04..52d110ee 100644 --- a/include/babeltrace2/trace-ir/packet.h +++ b/include/babeltrace2/trace-ir/packet.h @@ -35,20 +35,305 @@ extern "C" { #endif +/*! +@defgroup api-tir-pkt Packet +@ingroup api-tir + +@brief + Trace packet. + +A packet is a conceptual container of +\bt_p_ev within a \bt_stream. + +Some trace formats group events together within packets. This is the +case, for example, of the +Common Trace Format. + +Because a packet could contain millions of events, there are no actual +links from a packet to its events. However, there are links from a +packet's events to it (see bt_event_borrow_packet() and +bt_event_borrow_packet_const()). + +A packet can contain a context \bt_field which is data associated to +all the events of the packet. + +A packet is a \ref api-tir "trace IR" data object. + +A packet conceptually belongs to a \bt_stream. Borrow the stream of a +packet with bt_packet_borrow_stream() and +bt_packet_borrow_stream_const(). + +Before you create a packet for a given stream, the stream's class must +\ref api-tir-stream-cls-prop-supports-pkt "support packets". + +Create a packet with bt_packet_create(). You can then use this packet to +create a \bt_pb_msg and a \bt_pe_msg. + +A packet is a \ref api-fund-shared-object "shared object": get a +new reference with bt_packet_get_ref() and put an existing +reference with bt_packet_put_ref(). + +Some library functions \ref api-fund-freezing "freeze" packets on +success. The documentation of those functions indicate this +postcondition. + +The type of a packet is #bt_packet. + +
Property + | Value + |
---|---|
\ref api-tir-pkt-prop-ctx "Context field" + | + Unset instance of the + \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of + the \ref api-tir-stream-cls "class" of \bt_p{stream}. + |
bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
+ returns #BT_TRUE.
+*/
extern bt_packet *bt_packet_create(const bt_stream *stream);
+/*! @} */
+
+/*!
+@name Stream access
+@{
+*/
+
+/*!
+@brief
+ Borrows the \bt_stream conceptually containing the packet
+ \bt_p{packet}.
+
+@param[in] packet
+ Packet of which to borrow the stream conceptually containing it.
+
+@returns
+ \em Borrowed reference of the stream conceptually containing
+ \bt_p{packet}.
+
+@bt_pre_not_null{packet}
+
+@sa bt_packet_borrow_stream_const() —
+ \c const version of this function.
+*/
extern bt_stream *bt_packet_borrow_stream(bt_packet *packet);
+/*!
+@brief
+ Borrows the \bt_stream conceptually containing the packet
+ \bt_p{packet} (\c const version).
+
+See bt_packet_borrow_stream().
+*/
+extern const bt_stream *bt_packet_borrow_stream_const(
+ const bt_packet *packet);
+
+/*! @} */
+
+/*!
+@name Property
+@{
+*/
+
+/*!
+@brief
+ Borrows the context \bt_field of the packet \bt_p{packet}.
+
+See the \ref api-tir-pkt-prop-ctx "context field" property.
+
+@param[in] packet
+ Packet of which to borrow the context field.
+
+@returns
+ \em Borrowed reference of the context field of
+ \bt_p{packet}, or \c NULL if none.
+
+@bt_pre_not_null{packet}
+
+@sa bt_packet_borrow_context_field_const() —
+ \c const version of this function.
+*/
extern
bt_field *bt_packet_borrow_context_field(bt_packet *packet);
-typedef enum bt_packet_move_context_field_status {
- BT_PACKET_MOVE_CONTEXT_FIELD_STATUS_OK = __BT_FUNC_STATUS_OK,
-} bt_packet_move_context_field_status;
+/*!
+@brief
+ Borrows the context \bt_field of the packet \bt_p{packet}
+ (\c const version).
+See bt_packet_borrow_context_field().
+*/
extern
-bt_packet_move_context_field_status bt_packet_move_context_field(
- bt_packet *packet, bt_packet_context_field *context);
+const bt_field *bt_packet_borrow_context_field_const(
+ const bt_packet *packet);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+ Increments the \ref api-fund-shared-object "reference count" of
+ the packet \bt_p{packet}.
+
+@param[in] packet
+ @parblock
+ Packet of which to increment the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_packet_put_ref() —
+ Decrements the reference count of a packet.
+*/
+extern void bt_packet_get_ref(const bt_packet *packet);
+
+/*!
+@brief
+ Decrements the \ref api-fund-shared-object "reference count" of
+ the packet \bt_p{packet}.
+
+@param[in] packet
+ @parblock
+ Packet of which to decrement the reference count.
+
+ Can be \c NULL.
+ @endparblock
+
+@sa bt_packet_get_ref() —
+ Increments the reference count of a packet.
+*/
+extern void bt_packet_put_ref(const bt_packet *packet);
+
+/*!
+@brief
+ Decrements the reference count of the packet
+ \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
+
+@param _packet
+ @parblock
+ Packet of which to decrement the reference count.
+
+ Can contain \c NULL.
+ @endparblock
+
+@bt_pre_assign_expr{_packet}
+*/
+#define BT_PACKET_PUT_REF_AND_RESET(_packet) \
+ do { \
+ bt_packet_put_ref(_packet); \
+ (_packet) = NULL; \
+ } while (0)
+
+/*!
+@brief
+ Decrements the reference count of the packet \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 packet 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_PACKET_MOVE_REF(_dst, _src) \
+ do { \
+ bt_packet_put_ref(_dst); \
+ (_dst) = (_src); \
+ (_src) = NULL; \
+ } while (0)
+
+/*! @} */
+
+/*! @} */
#ifdef __cplusplus
}