include/lttng/action/rate-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_RATE_POLICY_H
   9 #define LTTNG_RATE_POLICY_H
  10
  11 #include <inttypes.h>
  12 #include <sys/types.h>
  13
  14 struct lttng_rate_policy;
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 enum lttng_rate_policy_status {
  21         LTTNG_RATE_POLICY_STATUS_OK = 0,
  22         LTTNG_RATE_POLICY_STATUS_ERROR = -1,
  23         LTTNG_RATE_POLICY_STATUS_UNKNOWN = -2,
  24         LTTNG_RATE_POLICY_STATUS_INVALID = -3,
  25         LTTNG_RATE_POLICY_STATUS_UNSET = -4,
  26         LTTNG_RATE_POLICY_STATUS_UNSUPPORTED = -5,
  27         LTTNG_RATE_POLICY_STATUS_PERMISSION_DENIED = -6,
  28 };
  29
  30 enum lttng_rate_policy_type {
  31         LTTNG_RATE_POLICY_TYPE_UNKNOWN = -1,
  32         LTTNG_RATE_POLICY_TYPE_EVERY_N = 0,
  33         LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N = 1,
  34 };
  35
  36 /*
  37  * Get the type of a rate policy.
  38  */
  39 extern enum lttng_rate_policy_type lttng_rate_policy_get_type(
  40                 const struct lttng_rate_policy *policy);
  41
  42 /*
  43  * Create a rate_policy of type `every n`.
  44  *
  45  * A `every n` rate policy will carry the execution of an action only when the
  46  * action was ready for execution for a multiple of N.
  47  *
  48  * Returns a rate_policy object on success, NULL on error.
  49  * rate_policy objects must be destroyed using the lttng_rate_policy_destroy()
  50  * function.
  51  */
  52 extern struct lttng_rate_policy *lttng_rate_policy_every_n_create(
  53                 uint64_t interval);
  54
  55 /*
  56  * Get the interval of a every N rate policy.
  57  *
  58  * Returns LTTNG_RATE_POLICY_STATUS_OK and a sets the interval.
  59  * on success, LTTNG_RATE_FIRING_POLICY_STATUS_INVALID if an invalid
  60  * parameter is passed.
  61  */
  62 extern enum lttng_rate_policy_status lttng_rate_policy_every_n_get_interval(
  63                 const struct lttng_rate_policy *policy, uint64_t *interval);
  64
  65 /*
  66  * Create a rate_policy of type `once after N`.
  67  *
  68  * A `once after N` rate policy will carry the execution of an action only when
  69  * the action was ready for execution at least N times and will only be carried
  70  * one time.
  71  *
  72  * Returns a rate_policy object on success, NULL on error.
  73  * rate_policy objects must be destroyed using the lttng_rate_policy_destroy()
  74  * function.
  75  */
  76 extern struct lttng_rate_policy *lttng_rate_policy_once_after_n_create(
  77                 uint64_t threshold);
  78
  79 /*
  80  * Get the threshold of a once after N rate policy.
  81  *
  82  * Returns LTTNG_RATE_POLICY_STATUS_OK and sets the threshold.
  83  * on success, LTTNG_RATE_POLICY_STATUS_INVALID if an invalid
  84  * parameter is passed.
  85  */
  86 extern enum lttng_rate_policy_status
  87 lttng_rate_policy_once_after_n_get_threshold(
  88                 const struct lttng_rate_policy *policy, uint64_t *threshold);
  89
  90 /*
  91  * Destroy (frees) a rate policy object.
  92  */
  93 extern void lttng_rate_policy_destroy(struct lttng_rate_policy *policy);
  94
  95 #ifdef __cplusplus
  96 }
  97 #endif
  98
  99 #endif /* LTTNG_rate_policy_H */