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