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