include/babeltrace2/trace-ir/field-path.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_FIELD_PATH_H
   8 #define BABELTRACE2_TRACE_IR_FIELD_PATH_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-field-path Field path
  26 @ingroup api-tir
  27
  28 @brief
  29     Path to a \bt_field.
  30
  31 A <strong><em>field path</em></strong> indicates how to reach a given
  32 \bt_field from a given <em>root scope</em>.
  33
  34 More specifically, a field path indicates how to reach:
  35
  36 - The length field of a \bt_darray_field (with a length field).
  37 - The selector field of a \bt_opt_field (with a selector field).
  38 - The selector field of a \bt_var_field (with a selector field).
  39
  40 You can borrow the field path from the \ref api-tir-fc "classes" of such
  41 fields with
  42 bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
  43 bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
  44 and
  45 bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
  46 Note that the field path properties of those field classes only becomes
  47 available when the field class becomes part of an \bt_ev_cls or of a
  48 \bt_stream_cls. See
  49 \ref api-tir-fc-link "Field classes with links to other field classes".
  50
  51 A field path is a \ref api-tir "trace IR" metadata object.
  52
  53 A field path is a \ref api-fund-shared-object "shared object": get a
  54 new reference with bt_field_path_get_ref() and put an existing
  55 reference with bt_field_path_put_ref().
  56
  57 The type of a field path is #bt_field_path.
  58
  59 <h1>Properties</h1>
  60
  61 A field path has the following properties:
  62
  63 <dl>
  64   <dt>
  65     \anchor api-tir-field-path-prop-root
  66     Root scope
  67   </dt>
  68   <dd>
  69     Indicates from which \bt_struct_field to start a lookup.
  70
  71     See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
  72     learn more.
  73
  74     Get a field path's root scope with bt_field_path_get_root_scope().
  75   </dd>
  76
  77   <dt>
  78     \anchor api-tir-field-path-prop-items
  79     Items
  80   </dt>
  81   <dd>
  82     Each item in a field path's item list indicates which action to take
  83     to follow the path to the linked \bt_field.
  84
  85     See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
  86     learn more.
  87
  88     Get the number of items in a field path with
  89     bt_field_path_get_item_count().
  90
  91     Borrow an item from a field path with
  92     bt_field_path_borrow_item_by_index_const(). This function
  93     returns the #bt_field_path_item type.
  94
  95     A field path item is a \ref api-fund-unique-object "unique object":
  96     it belongs to the field path which contains it.
  97   </dd>
  98 </dl>
  99
 100 <h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
 101
 102 The field resolution algorithm using a field path is:
 103
 104 -# Use the appropriate function to set a <em>current field</em> variable
 105    from the root scope (as returned by bt_field_path_get_root_scope()):
 106
 107    <dl>
 108      <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
 109      <dd>
 110        bt_packet_borrow_context_field_const().
 111      </dd>
 112      <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
 113      <dd>
 114        bt_event_borrow_common_context_field_const().
 115      </dd>
 116      <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
 117      <dd>
 118        bt_event_borrow_specific_context_field_const().
 119      </dd>
 120      <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
 121      <dd>
 122        bt_event_borrow_payload_field_const().
 123      </dd>
 124    </dl>
 125
 126 -# For each field path item (use bt_field_path_get_item_count()
 127    and bt_field_path_borrow_item_by_index_const()), depending on
 128    the item's type (as returned by bt_field_path_item_get_type()):
 129
 130    <dl>
 131      <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
 132      <dd>
 133        Call bt_field_path_item_index_get_index() to get the item's
 134        index value.
 135
 136        Depending on the current field's class's type (as
 137        returned by bt_field_get_class_type()):
 138
 139        <dl>
 140          <dt>\bt_c_struct_fc</dt>
 141          <dd>
 142            Call bt_field_structure_borrow_member_field_by_index_const()
 143            with the current field and with the item's index to set the
 144            new current field.
 145          </dd>
 146
 147          <dt>\bt_c_var_fc</dt>
 148          <dd>
 149            Call bt_field_variant_borrow_selected_option_field_const()
 150            with the current field to set the new current field.
 151          </dd>
 152        </dl>
 153      </dd>
 154
 155      <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
 156      <dd>
 157        Call bt_field_array_borrow_element_field_by_index_const()
 158        with the index of the field eventually containing the
 159        field with a link (\bt_darray_field, \bt_opt_field, or
 160        \bt_var_field) and the current field to set the new current
 161        field.
 162      </dd>
 163
 164      <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
 165      <dd>
 166        Call bt_field_option_borrow_field_const() with the current
 167        field to set the new current field.
 168      </dd>
 169    </dl>
 170
 171 After applying this procedure, the current field is the linked
 172 field.
 173 */
 174
 175 /*! @{ */
 176
 177 /*!
 178 @name Field path
 179 @{
 180
 181 @typedef struct bt_field_path bt_field_path;
 182
 183 @brief
 184     Field path.
 185
 186 */
 187
 188 /*!
 189 @brief
 190     Field path scopes.
 191 */
 192 typedef enum bt_field_path_scope {
 193         /*!
 194         @brief
 195             Packet context.
 196         */
 197         BT_FIELD_PATH_SCOPE_PACKET_CONTEXT              = 0,
 198
 199         /*!
 200         @brief
 201             Event common context.
 202         */
 203         BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT        = 1,
 204
 205         /*!
 206         @brief
 207             Event specific context.
 208         */
 209         BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT      = 2,
 210
 211         /*!
 212         @brief
 213             Event payload.
 214         */
 215         BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD               = 3,
 216 } bt_field_path_scope;
 217
 218 /*!
 219 @brief
 220     Returns the root scope of the field path \bt_p{field_path}.
 221
 222 See the \ref api-tir-field-path-prop-root "root scope" property.
 223
 224 @param[in] field_path
 225     Field path of which to get the root scope.
 226
 227 @returns
 228     Root scope of \bt_p{field_path}.
 229
 230 @bt_pre_not_null{field_path}
 231 */
 232 extern bt_field_path_scope bt_field_path_get_root_scope(
 233                 const bt_field_path *field_path) __BT_NOEXCEPT;
 234
 235 /*!
 236 @brief
 237     Returns the number of items contained in the field path
 238     \bt_p{field_path}.
 239
 240 See the \ref api-tir-field-path-prop-items "items" property.
 241
 242 @param[in] field_path
 243     Field path of which to get the number of contained items.
 244
 245 @returns
 246     Number of contained items in \bt_p{field_path}.
 247
 248 @bt_pre_not_null{field_path}
 249 */
 250 extern uint64_t bt_field_path_get_item_count(
 251                 const bt_field_path *field_path) __BT_NOEXCEPT;
 252
 253 /*!
 254 @brief
 255     Borrows the item at index \bt_p{index} from the
 256     field path \bt_p{field_path}.
 257
 258 See the \ref api-tir-field-path-prop-items "items" property.
 259
 260 @param[in] field_path
 261     Field path from which to borrow the item at index \bt_p{index}.
 262 @param[in] index
 263     Index of the item to borrow from \bt_p{field_path}.
 264
 265 @returns
 266     @parblock
 267     \em Borrowed reference of the item of
 268     \bt_p{field_path} at index \bt_p{index}.
 269
 270     The returned pointer remains valid as long as \bt_p{field_path}
 271     exists.
 272     @endparblock
 273
 274 @bt_pre_not_null{field_path}
 275 @pre
 276     \bt_p{index} is less than the number of items in
 277     \bt_p{field_path} (as returned by bt_field_path_get_item_count()).
 278
 279 @sa bt_field_path_get_item_count() &mdash;
 280     Returns the number of items contained in a field path.
 281 */
 282 extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
 283                 const bt_field_path *field_path, uint64_t index) __BT_NOEXCEPT;
 284
 285 /*!
 286 @brief
 287     Increments the \ref api-fund-shared-object "reference count" of
 288     the field path \bt_p{field_path}.
 289
 290 @param[in] field_path
 291     @parblock
 292     Field path of which to increment the reference count.
 293
 294     Can be \c NULL.
 295     @endparblock
 296
 297 @sa bt_field_path_put_ref() &mdash;
 298     Decrements the reference count of a field path.
 299 */
 300 extern void bt_field_path_get_ref(const bt_field_path *field_path)
 301                 __BT_NOEXCEPT;
 302
 303 /*!
 304 @brief
 305     Decrements the \ref api-fund-shared-object "reference count" of
 306     the field path \bt_p{field_path}.
 307
 308 @param[in] field_path
 309     @parblock
 310     Field path of which to decrement the reference count.
 311
 312     Can be \c NULL.
 313     @endparblock
 314
 315 @sa bt_field_path_get_ref() &mdash;
 316     Increments the reference count of a field path.
 317 */
 318 extern void bt_field_path_put_ref(const bt_field_path *field_path)
 319                 __BT_NOEXCEPT;
 320
 321 /*!
 322 @brief
 323     Decrements the reference count of the field path
 324     \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
 325
 326 @param _field_path
 327     @parblock
 328     Field path of which to decrement the reference count.
 329
 330     Can contain \c NULL.
 331     @endparblock
 332
 333 @bt_pre_assign_expr{_field_path}
 334 */
 335 #define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)    \
 336         do {                                            \
 337                 bt_field_path_put_ref(_field_path);     \
 338                 (_field_path) = NULL;                   \
 339         } while (0)
 340
 341 /*!
 342 @brief
 343     Decrements the reference count of the field path \bt_p{_dst}, sets
 344     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 345
 346 This macro effectively moves a field path reference from the expression
 347 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 348 \bt_p{_dst} reference.
 349
 350 @param _dst
 351     @parblock
 352     Destination expression.
 353
 354     Can contain \c NULL.
 355     @endparblock
 356 @param _src
 357     @parblock
 358     Source expression.
 359
 360     Can contain \c NULL.
 361     @endparblock
 362
 363 @bt_pre_assign_expr{_dst}
 364 @bt_pre_assign_expr{_src}
 365 */
 366 #define BT_FIELD_PATH_MOVE_REF(_dst, _src)      \
 367         do {                                    \
 368                 bt_field_path_put_ref(_dst);    \
 369                 (_dst) = (_src);                \
 370                 (_src) = NULL;                  \
 371         } while (0)
 372
 373 /*! @} */
 374
 375 /*!
 376 @name Field path item
 377 @{
 378
 379 @typedef struct bt_field_path_item bt_field_path_item;
 380
 381 @brief
 382     Field path item.
 383
 384 */
 385
 386 /*!
 387 @brief
 388     Field path item type enumerators.
 389 */
 390 typedef enum bt_field_path_item_type {
 391         /*!
 392         @brief
 393             Index of a \bt_struct_field member or selected \bt_var_field
 394             option's field.
 395         */
 396         BT_FIELD_PATH_ITEM_TYPE_INDEX                           = 1 << 0,
 397
 398         /*!
 399         @brief
 400             Common field of an \bt_array_field.
 401         */
 402         BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT           = 1 << 1,
 403
 404         /*!
 405         @brief
 406             Current field of an \bt_opt_field.
 407         */
 408         BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT          = 1 << 2,
 409 } bt_field_path_item_type;
 410
 411 /*!
 412 @brief
 413     Returns the type enumerator of the field path item
 414     \bt_p{item}.
 415
 416 See the \ref api-tir-field-path-prop-items "items" property.
 417
 418 @param[in] item
 419     Field path item of which to get the type enumerator
 420
 421 @returns
 422     Type enumerator of \bt_p{item}.
 423
 424 @bt_pre_not_null{item}
 425 */
 426 extern bt_field_path_item_type bt_field_path_item_get_type(
 427                 const bt_field_path_item *item) __BT_NOEXCEPT;
 428
 429 /*!
 430 @brief
 431     Returns the index value of the index field path item
 432     \bt_p{item}.
 433
 434 See the \ref api-tir-field-path-prop-items "items" property.
 435
 436 @param[in] item
 437     Index field path item of which to get the index value.
 438
 439 @returns
 440     Index value of \bt_p{item}.
 441
 442 @bt_pre_not_null{item}
 443 @pre
 444     \bt_p{item} is an index field path item
 445     (bt_field_path_item_get_type() returns
 446     #BT_FIELD_PATH_ITEM_TYPE_INDEX).
 447 */
 448 extern uint64_t bt_field_path_item_index_get_index(
 449                 const bt_field_path_item *item) __BT_NOEXCEPT;
 450
 451 /*! @} */
 452
 453 /*! @} */
 454
 455 #ifdef __cplusplus
 456 }
 457 #endif
 458
 459 #endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */