include/lttng/action/path.h

   1 /*
   2  * Copyright (C) 2021 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_ACTION_PATH_H
   9 #define LTTNG_ACTION_PATH_H
  10
  11 #include <lttng/lttng-export.h>
  12 #include <stdint.h>
  13 #include <stddef.h>
  14
  15 struct lttng_action_path;
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 enum lttng_action_path_status {
  22         LTTNG_ACTION_PATH_STATUS_OK = 0,
  23         LTTNG_ACTION_PATH_STATUS_INVALID = -1,
  24 };
  25
  26 /*
  27  * Create a path to an action.
  28  *
  29  * An action path indicates how to reach a given action from the action
  30  * of a trigger. The action of a trigger is implicitly the root of an action
  31  * path.
  32  *
  33  * The indexes of an action path allow the resolution of an action.
  34  * The indexes that make-up an action path indicate the index of the successive
  35  * action lists that must be traversed to reach the target action.
  36  *
  37  * For instance, an action path that has a single index 'N' implies that:
  38  *   - The root action is a list,
  39  *   - The target action is the 'N'-th action in that list.
  40  *
  41  * An action path with two indexes, N1 and N2 implies that:
  42  *   - The root action is an action list (L1),
  43  *   - The N1-th action of the action list (L1) is also a list (L2),
  44  *   - The target action is the N2-th action of the L2 list.
  45  *
  46  * The `indexes` are copied internally and can be disposed-of by the caller.
  47  */
  48 LTTNG_EXPORT extern struct lttng_action_path *lttng_action_path_create(
  49                 const uint64_t *indexes, size_t index_count);
  50
  51 /*
  52  * Get the count of indexes in an action path.
  53  */
  54 LTTNG_EXPORT extern enum lttng_action_path_status lttng_action_path_get_index_count(
  55                 const struct lttng_action_path *path, size_t *index_count);
  56
  57 /*
  58  * Get an index from an action path.
  59  */
  60 LTTNG_EXPORT extern enum lttng_action_path_status lttng_action_path_get_index_at_index(
  61                 const struct lttng_action_path *path,
  62                 size_t path_index,
  63                 uint64_t *out_index);
  64
  65 /*
  66  * Destroy an action path object.
  67  */
  68 LTTNG_EXPORT extern void lttng_action_path_destroy(struct lttng_action_path *action_path);
  69
  70 #ifdef __cplusplus
  71 }
  72 #endif
  73
  74 #endif /* LTTNG_ACTION_PATH_H */