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);
 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);
 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);
 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
 302 /*!
 303 @brief
 304     Decrements the \ref api-fund-shared-object "reference count" of
 305     the field path \bt_p{field_path}.
 306
 307 @param[in] field_path
 308     @parblock
 309     Field path of which to decrement the reference count.
 310
 311     Can be \c NULL.
 312     @endparblock
 313
 314 @sa bt_field_path_get_ref() &mdash;
 315     Increments the reference count of a field path.
 316 */
 317 extern void bt_field_path_put_ref(const bt_field_path *field_path);
 318
 319 /*!
 320 @brief
 321     Decrements the reference count of the field path
 322     \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
 323
 324 @param _field_path
 325     @parblock
 326     Field path of which to decrement the reference count.
 327
 328     Can contain \c NULL.
 329     @endparblock
 330
 331 @bt_pre_assign_expr{_field_path}
 332 */
 333 #define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)    \
 334         do {                                            \
 335                 bt_field_path_put_ref(_field_path);     \
 336                 (_field_path) = NULL;                   \
 337         } while (0)
 338
 339 /*!
 340 @brief
 341     Decrements the reference count of the field path \bt_p{_dst}, sets
 342     \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
 343
 344 This macro effectively moves a field path reference from the expression
 345 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
 346 \bt_p{_dst} reference.
 347
 348 @param _dst
 349     @parblock
 350     Destination expression.
 351
 352     Can contain \c NULL.
 353     @endparblock
 354 @param _src
 355     @parblock
 356     Source expression.
 357
 358     Can contain \c NULL.
 359     @endparblock
 360
 361 @bt_pre_assign_expr{_dst}
 362 @bt_pre_assign_expr{_src}
 363 */
 364 #define BT_FIELD_PATH_MOVE_REF(_dst, _src)      \
 365         do {                                    \
 366                 bt_field_path_put_ref(_dst);    \
 367                 (_dst) = (_src);                \
 368                 (_src) = NULL;                  \
 369         } while (0)
 370
 371 /*! @} */
 372
 373 /*!
 374 @name Field path item
 375 @{
 376
 377 @typedef struct bt_field_path_item bt_field_path_item;
 378
 379 @brief
 380     Field path item.
 381
 382 */
 383
 384 /*!
 385 @brief
 386     Field path item type enumerators.
 387 */
 388 typedef enum bt_field_path_item_type {
 389         /*!
 390         @brief
 391             Index of a \bt_struct_field member or selected \bt_var_field
 392             option's field.
 393         */
 394         BT_FIELD_PATH_ITEM_TYPE_INDEX                           = 1 << 0,
 395
 396         /*!
 397         @brief
 398             Common field of an \bt_array_field.
 399         */
 400         BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT           = 1 << 1,
 401
 402         /*!
 403         @brief
 404             Current field of an \bt_opt_field.
 405         */
 406         BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT          = 1 << 2,
 407 } bt_field_path_item_type;
 408
 409 /*!
 410 @brief
 411     Returns the type enumerator of the field path item
 412     \bt_p{item}.
 413
 414 See the \ref api-tir-field-path-prop-items "items" property.
 415
 416 @param[in] item
 417     Field path item of which to get the type enumerator
 418
 419 @returns
 420     Type enumerator of \bt_p{item}.
 421
 422 @bt_pre_not_null{item}
 423 */
 424 extern bt_field_path_item_type bt_field_path_item_get_type(
 425                 const bt_field_path_item *item);
 426
 427 /*!
 428 @brief
 429     Returns the index value of the index field path item
 430     \bt_p{item}.
 431
 432 See the \ref api-tir-field-path-prop-items "items" property.
 433
 434 @param[in] item
 435     Index field path item of which to get the index value.
 436
 437 @returns
 438     Index value of \bt_p{item}.
 439
 440 @bt_pre_not_null{item}
 441 @pre
 442     \bt_p{item} is an index field path item
 443     (bt_field_path_item_get_type() returns
 444     #BT_FIELD_PATH_ITEM_TYPE_INDEX).
 445 */
 446 extern uint64_t bt_field_path_item_index_get_index(
 447                 const bt_field_path_item *item);
 448
 449 /*! @} */
 450
 451 /*! @} */
 452
 453 #ifdef __cplusplus
 454 }
 455 #endif
 456
 457 #endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */