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