include/babeltrace2/trace-ir/packet.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_TRACE_IR_PACKET_H
   8 #define BABELTRACE2_TRACE_IR_PACKET_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <stdint.h>
  17
  18 #include <babeltrace2/types.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25 @defgroup api-tir-pkt Packet
  26 @ingroup api-tir
  27
  28 @brief
  29     Trace packet.
  30
  31 A <strong><em>packet</em></strong> is a conceptual container of
  32 \bt_p_ev within a \bt_stream.
  33
  34 Some trace formats group events together within packets. This is the
  35 case, for example, of the
  36 <a href="https://diamon.org/ctf/">Common Trace Format</a>.
  37
  38 Because a packet could contain millions of events, there are no actual
  39 links from a packet to its events. However, there are links from a
  40 packet's events to it (see bt_event_borrow_packet() and
  41 bt_event_borrow_packet_const()).
  42
  43 A packet can contain a context \bt_field which is data associated to
  44 all the events of the packet.
  45
  46 A packet is a \ref api-tir "trace IR" data object.
  47
  48 A packet conceptually belongs to a \bt_stream. Borrow the stream of a
  49 packet with bt_packet_borrow_stream() and
  50 bt_packet_borrow_stream_const().
  51
  52 Before you create a packet for a given stream, the stream's class must
  53 \ref api-tir-stream-cls-prop-supports-pkt "support packets".
  54
  55 Create a packet with bt_packet_create(). You can then use this packet to
  56 create a \bt_pb_msg and a \bt_pe_msg.
  57
  58 A packet is a \ref api-fund-shared-object "shared object": get a
  59 new reference with bt_packet_get_ref() and put an existing
  60 reference with bt_packet_put_ref().
  61
  62 Some library functions \ref api-fund-freezing "freeze" packets on
  63 success. The documentation of those functions indicate this
  64 postcondition.
  65
  66 The type of a packet is #bt_packet.
  67
  68 <h1>Property</h1>
  69
  70 A packet has the following property:
  71
  72 <dl>
  73   <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
  74   <dd>
  75     Packet's context \bt_field.
  76
  77     The context of a packet contains data associated to all its
  78     events.
  79
  80     The \ref api-tir-fc "class" of a packet's context field is set
  81     at the packet's \bt_stream_cls level. See
  82     bt_stream_class_set_packet_context_field_class()
  83     bt_stream_class_borrow_packet_context_field_class(),
  84     and bt_stream_class_borrow_packet_context_field_class_const()
  85
  86     Use bt_packet_borrow_context_field() and
  87     bt_packet_borrow_context_field_const().
  88   </dd>
  89 </dl>
  90 */
  91
  92 /*! @{ */
  93
  94 /*!
  95 @name Type
  96 @{
  97
  98 @typedef struct bt_packet bt_packet;
  99
 100 @brief
 101     Packet.
 102
 103 @}
 104 */
 105
 106 /*!
 107 @name Creation
 108 @{
 109 */
 110
 111 /*!
 112 @brief
 113     Creates a packet for the \bt_stream \bt_p{stream}.
 114
 115 @attention
 116     @parblock
 117     Only use this function if
 118
 119     @code
 120     bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
 121     @endcode
 122
 123     returns #BT_TRUE.
 124     @endparblock
 125
 126 On success, the returned packet has the following property value:
 127
 128 <table>
 129   <tr>
 130     <th>Property
 131     <th>Value
 132   <tr>
 133     <td>\ref api-tir-pkt-prop-ctx "Context field"
 134     <td>
 135       Unset instance of the
 136       \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
 137       the \ref api-tir-stream-cls "class" of \bt_p{stream}.
 138 </table>
 139
 140 @param[in] stream
 141     Stream for which to create the packet.
 142
 143 @returns
 144     New packet reference, or \c NULL on memory error.
 145
 146 @pre
 147     <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
 148     returns #BT_TRUE.
 149 */
 150 extern bt_packet *bt_packet_create(const bt_stream *stream) __BT_NOEXCEPT;
 151
 152 /*! @} */
 153
 154 /*!
 155 @name Stream access
 156 @{
 157 */
 158
 159 /*!
 160 @brief
 161     Borrows the \bt_stream conceptually containing the packet
 162     \bt_p{packet}.
 163
 164 @param[in] packet
 165     Packet of which to borrow the stream conceptually containing it.
 166
 167 @returns
 168     \em Borrowed reference of the stream conceptually containing
 169     \bt_p{packet}.
 170
 171 @bt_pre_not_null{packet}
 172
 173 @sa bt_packet_borrow_stream_const() &mdash;
 174     \c const version of this function.
 175 */
 176 extern bt_stream *bt_packet_borrow_stream(bt_packet *packet) __BT_NOEXCEPT;
 177
 178 /*!
 179 @brief
 180     Borrows the \bt_stream conceptually containing the packet
 181     \bt_p{packet} (\c const version).
 182
 183 See bt_packet_borrow_stream().
 184 */
 185 extern const bt_stream *bt_packet_borrow_stream_const(
 186                 const bt_packet *packet) __BT_NOEXCEPT;
 187
 188 /*! @} */
 189
 190 /*!
 191 @name Property
 192 @{
 193 */
 194
 195 /*!
 196 @brief
 197     Borrows the context \bt_field of the packet \bt_p{packet}.
 198
 199 See the \ref api-tir-pkt-prop-ctx "context field" property.
 200
 201 @param[in] packet
 202     Packet of which to borrow the context field.
 203
 204 @returns
 205     \em Borrowed reference of the context field of
 206     \bt_p{packet}, or \c NULL if none.
 207
 208 @bt_pre_not_null{packet}
 209
 210 @sa bt_packet_borrow_context_field_const() &mdash;
 211     \c const version of this function.
 212 */
 213 extern
 214 bt_field *bt_packet_borrow_context_field(bt_packet *packet) __BT_NOEXCEPT;
 215
 216 /*!
 217 @brief
 218     Borrows the context \bt_field of the packet \bt_p{packet}
 219     (\c const version).
 220
 221 See bt_packet_borrow_context_field().
 222 */
 223 extern
 224 const bt_field *bt_packet_borrow_context_field_const(
 225                 const bt_packet *packet) __BT_NOEXCEPT;
 226
 227 /*! @} */
 228
 229 /*!
 230 @name Reference count
 231 @{
 232 */
 233
 234 /*!
 235 @brief
 236     Increments the \ref api-fund-shared-object "reference count" of
 237     the packet \bt_p{packet}.
 238
 239 @param[in] packet
 240     @parblock
 241     Packet of which to increment the reference count.
 242
 243     Can be \c NULL.
 244     @endparblock
 245
 246 @sa bt_packet_put_ref() &mdash;
 247     Decrements the reference count of a packet.
 248 */
 249 extern void bt_packet_get_ref(const bt_packet *packet) __BT_NOEXCEPT;
 250
 251 /*!
 252 @brief
 253     Decrements the \ref api-fund-shared-object "reference count" of
 254     the packet \bt_p{packet}.
 255
 256 @param[in] packet
 257     @parblock
 258     Packet of which to decrement the reference count.
 259
 260     Can be \c NULL.
 261     @endparblock
 262
 263 @sa bt_packet_get_ref() &mdash;
 264     Increments the reference count of a packet.
 265 */
 266 extern void bt_packet_put_ref(const bt_packet *packet) __BT_NOEXCEPT;
 267
 268 /*!
 269 @brief
 270     Decrements the reference count of the packet
 271     \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
 272
 273 @param _packet
 274     @parblock
 275     Packet of which to decrement the reference count.
 276
 277     Can contain \c NULL.
 278     @endparblock
 279
 280 @bt_pre_assign_expr{_packet}
 281 */
 282 #define BT_PACKET_PUT_REF_AND_RESET(_packet)            \
 283         do {                                            \
 284                 bt_packet_put_ref(_packet);             \
 285                 (_packet) = NULL;                       \
 286         } while (0)
 287
 288 /*!
 289 @brief
 290     Decrements the reference count of the packet \bt_p{_dst}, sets
 291     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 292
 293 This macro effectively moves a packet reference from the expression
 294 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 295 \bt_p{_dst} reference.
 296
 297 @param _dst
 298     @parblock
 299     Destination expression.
 300
 301     Can contain \c NULL.
 302     @endparblock
 303 @param _src
 304     @parblock
 305     Source expression.
 306
 307     Can contain \c NULL.
 308     @endparblock
 309
 310 @bt_pre_assign_expr{_dst}
 311 @bt_pre_assign_expr{_src}
 312 */
 313 #define BT_PACKET_MOVE_REF(_dst, _src)          \
 314         do {                                    \
 315                 bt_packet_put_ref(_dst);        \
 316                 (_dst) = (_src);                \
 317                 (_src) = NULL;                  \
 318         } while (0)
 319
 320 /*! @} */
 321
 322 /*! @} */
 323
 324 #ifdef __cplusplus
 325 }
 326 #endif
 327
 328 #endif /* BABELTRACE2_TRACE_IR_PACKET_H */