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