[lttng-tools.git] / include / lttng / action / rate-policy.h

/*
 * Copyright (C) 2021 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_RATE_POLICY_H
#define LTTNG_RATE_POLICY_H

#include <lttng/lttng-export.h>

#include <inttypes.h>
#include <sys/types.h>

struct lttng_rate_policy;

#ifdef __cplusplus
extern "C" {
#endif

enum lttng_rate_policy_status {
	LTTNG_RATE_POLICY_STATUS_OK = 0,
	LTTNG_RATE_POLICY_STATUS_ERROR = -1,
	LTTNG_RATE_POLICY_STATUS_UNKNOWN = -2,
	LTTNG_RATE_POLICY_STATUS_INVALID = -3,
	LTTNG_RATE_POLICY_STATUS_UNSET = -4,
	LTTNG_RATE_POLICY_STATUS_UNSUPPORTED = -5,
	LTTNG_RATE_POLICY_STATUS_PERMISSION_DENIED = -6,
};

enum lttng_rate_policy_type {
	LTTNG_RATE_POLICY_TYPE_UNKNOWN = -1,
	LTTNG_RATE_POLICY_TYPE_EVERY_N = 0,
	LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N = 1,
};

/*
 * Get the type of a rate policy.
 */
LTTNG_EXPORT extern enum lttng_rate_policy_type
lttng_rate_policy_get_type(const struct lttng_rate_policy *policy);

/*
 * Create a rate_policy of type `every n`.
 *
 * A `every n` rate policy will carry the execution of an action only when the
 * action was ready for execution for a multiple of N.
 *
 * Returns a rate_policy object on success, NULL on error.
 * rate_policy objects must be destroyed using the lttng_rate_policy_destroy()
 * function.
 */
LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_every_n_create(uint64_t interval);

/*
 * Get the interval of a every N rate policy.
 *
 * Returns LTTNG_RATE_POLICY_STATUS_OK and a sets the interval.
 * on success, LTTNG_RATE_FIRING_POLICY_STATUS_INVALID if an invalid
 * parameter is passed.
 */
LTTNG_EXPORT extern enum lttng_rate_policy_status
lttng_rate_policy_every_n_get_interval(const struct lttng_rate_policy *policy, uint64_t *interval);

/*
 * Create a rate_policy of type `once after N`.
 *
 * A `once after N` rate policy will carry the execution of an action only when
 * the action was ready for execution at least N times and will only be carried
 * one time.
 *
 * Returns a rate_policy object on success, NULL on error.
 * rate_policy objects must be destroyed using the lttng_rate_policy_destroy()
 * function.
 */
LTTNG_EXPORT extern struct lttng_rate_policy *
lttng_rate_policy_once_after_n_create(uint64_t threshold);

/*
 * Get the threshold of a once after N rate policy.
 *
 * Returns LTTNG_RATE_POLICY_STATUS_OK and sets the threshold.
 * on success, LTTNG_RATE_POLICY_STATUS_INVALID if an invalid
 * parameter is passed.
 */
LTTNG_EXPORT extern enum lttng_rate_policy_status
lttng_rate_policy_once_after_n_get_threshold(const struct lttng_rate_policy *policy,
					     uint64_t *threshold);

/*
 * Destroy (frees) a rate policy object.
 */
LTTNG_EXPORT extern void lttng_rate_policy_destroy(struct lttng_rate_policy *policy);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_rate_policy_H */
Commit	Line	Data
7f4d5b07 JR	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
4bd69c5f	11	#include <lttng/lttng-export.h>
28f23191 JG	12
28f23191 JG	13	#include <inttypes.h>
7f4d5b07 JR	14	#include <sys/types.h>
	15
	16	struct lttng_rate_policy;
	17
	18	#ifdef __cplusplus
	19	extern "C" {
	20	#endif
	21
	22	enum lttng_rate_policy_status {
	23	LTTNG_RATE_POLICY_STATUS_OK = 0,
	24	LTTNG_RATE_POLICY_STATUS_ERROR = -1,
	25	LTTNG_RATE_POLICY_STATUS_UNKNOWN = -2,
	26	LTTNG_RATE_POLICY_STATUS_INVALID = -3,
	27	LTTNG_RATE_POLICY_STATUS_UNSET = -4,
	28	LTTNG_RATE_POLICY_STATUS_UNSUPPORTED = -5,
	29	LTTNG_RATE_POLICY_STATUS_PERMISSION_DENIED = -6,
	30	};
	31
	32	enum lttng_rate_policy_type {
	33	LTTNG_RATE_POLICY_TYPE_UNKNOWN = -1,
	34	LTTNG_RATE_POLICY_TYPE_EVERY_N = 0,
	35	LTTNG_RATE_POLICY_TYPE_ONCE_AFTER_N = 1,
	36	};
	37
	38	/*
	39	* Get the type of a rate policy.
	40	*/
28f23191 JG	41	LTTNG_EXPORT extern enum lttng_rate_policy_type
28f23191 JG	42	lttng_rate_policy_get_type(const struct lttng_rate_policy *policy);
7f4d5b07 JR	43
	44	/*
	45	* Create a rate_policy of type `every n`.
	46	*
	47	* A `every n` rate policy will carry the execution of an action only when the
	48	* action was ready for execution for a multiple of N.
	49	*
	50	* Returns a rate_policy object on success, NULL on error.
	51	* rate_policy objects must be destroyed using the lttng_rate_policy_destroy()
	52	* function.
	53	*/
28f23191	54	LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_every_n_create(uint64_t interval);
7f4d5b07 JR	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	*/
28f23191 JG	63	LTTNG_EXPORT extern enum lttng_rate_policy_status
28f23191 JG	64	lttng_rate_policy_every_n_get_interval(const struct lttng_rate_policy policy, uint64_t interval);
7f4d5b07 JR	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	*/
28f23191 JG	77	LTTNG_EXPORT extern struct lttng_rate_policy *
28f23191 JG	78	lttng_rate_policy_once_after_n_create(uint64_t threshold);
7f4d5b07 JR	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	*/
4bd69c5f	87	LTTNG_EXPORT extern enum lttng_rate_policy_status
28f23191 JG	88	lttng_rate_policy_once_after_n_get_threshold(const struct lttng_rate_policy *policy,
28f23191 JG	89	uint64_t *threshold);
7f4d5b07 JR	90
	91	/*
	92	* Destroy (frees) a rate policy object.
	93	*/
4bd69c5f	94	LTTNG_EXPORT extern void lttng_rate_policy_destroy(struct lttng_rate_policy *policy);
7f4d5b07 JR	95
	96	#ifdef __cplusplus
	97	}
	98	#endif
	99
	100	#endif /* LTTNG_rate_policy_H */