include/lttng/action/firing-policy.h

   1 /*
   2  * Copyright (C) 2021 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_FIRING_POLICY_H
   9 #define LTTNG_FIRING_POLICY_H
  10
  11 #include <inttypes.h>
  12 #include <sys/types.h>
  13
  14 struct lttng_firing_policy;
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 enum lttng_firing_policy_status {
  21         LTTNG_FIRING_POLICY_STATUS_OK = 0,
  22         LTTNG_FIRING_POLICY_STATUS_ERROR = -1,
  23         LTTNG_FIRING_POLICY_STATUS_UNKNOWN = -2,
  24         LTTNG_FIRING_POLICY_STATUS_INVALID = -3,
  25         LTTNG_FIRING_POLICY_STATUS_UNSET = -4,
  26         LTTNG_FIRING_POLICY_STATUS_UNSUPPORTED = -5,
  27 };
  28
  29 enum lttng_firing_policy_type {
  30         LTTNG_FIRING_POLICY_TYPE_UNKNOWN = -1,
  31         LTTNG_FIRING_POLICY_TYPE_EVERY_N = 0,
  32         LTTNG_FIRING_POLICY_TYPE_ONCE_AFTER_N = 1,
  33 };
  34
  35 /*
  36  * Get the type of a firing policy.
  37  */
  38 extern enum lttng_firing_policy_type lttng_firing_policy_get_type(
  39                 const struct lttng_firing_policy *policy);
  40
  41 /*
  42  * Create a firing_policy of type `every n`.
  43  *
  44  * A `every n` firing policy will carry the execution of an action only when the
  45  * action was ready for execution for a multiple of N.
  46  *
  47  * Returns a firing_policy object on success, NULL on error.
  48  * firing_policy objects must be destroyed using the
  49  * lttng_firing_policy_destroy() function.
  50  */
  51 extern struct lttng_firing_policy *lttng_firing_policy_every_n_create(
  52                 uint64_t interval);
  53
  54 /*
  55  * Get the interval of a every N firing policy.
  56  *
  57  * Returns LTTNG_FIRING_POLICY_STATUS_OK and a sets the interval.
  58  * on success, LTTNG_FIRING_POLICY_STATUS_INVALID if an invalid
  59  * parameter is passed.
  60  */
  61 extern enum lttng_firing_policy_status lttng_firing_policy_every_n_get_interval(
  62                 const struct lttng_firing_policy *policy, uint64_t *interval);
  63
  64 /*
  65  * Create a firing_policy of type `once after N`.
  66  *
  67  * A `once after N` firing policy will carry the execution of an action only
  68  * when the action was ready for execution at least N times and will only be
  69  * carried one time.
  70  *
  71  * Returns a firing_policy object on success, NULL on error.
  72  * firing_policy objects must be destroyed using the
  73  * lttng_firing_policy_destroy() function.
  74  */
  75 extern struct lttng_firing_policy *lttng_firing_policy_once_after_n_create(
  76                 uint64_t threshold);
  77
  78 /*
  79  * Get the threshold of a once after N firing policy.
  80  *
  81  * Returns LTTNG_FIRING_POLICY_STATUS_OK and sets the threshold.
  82  * on success, LTTNG_FIRING_POLICY_STATUS_INVALID if an invalid
  83  * parameter is passed.
  84  */
  85 extern enum lttng_firing_policy_status
  86 lttng_firing_policy_once_after_n_get_threshold(
  87                 const struct lttng_firing_policy *policy, uint64_t *threshold);
  88
  89 /*
  90  * Destroy (frees) a firing policy object.
  91  */
  92 extern void lttng_firing_policy_destroy(struct lttng_firing_policy *policy);
  93
  94 #ifdef __cplusplus
  95 }
  96 #endif
  97
  98 #endif /* LTTNG_FIRING_POLICY_H */