include/babeltrace2/trace-ir/field-path.h

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