include/babeltrace2/trace-ir/packet.h

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