Add missing include for ssize_t on Cygwin
[lttng-tools.git] / include / lttng / condition / buffer-usage.h
1 /*
2 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License, version 2.1 only,
6 * as published by the Free Software Foundation.
7 *
8 * This library is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11 * for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 */
17
18 #ifndef LTTNG_CONDITION_BUFFER_USAGE_H
19 #define LTTNG_CONDITION_BUFFER_USAGE_H
20
21 #include <lttng/condition/evaluation.h>
22 #include <lttng/condition/condition.h>
23 #include <stdint.h>
24 #include <lttng/domain.h>
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /**
31 * Buffer usage conditions allows an action to be taken whenever a channel's
32 * buffer usage crosses a set threshold.
33 *
34 * These conditions are periodically evaluated against the current buffer
35 * usage statistics. The period at which these conditions are evaluated is
36 * governed by the channels' monitor timer.
37 *
38 * Note that the use of these conditons does not imply any hysteresis-loop
39 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
40 * will fire everytime the buffer usage goes from a value < 75% to a value that
41 * is >= 75%. The evaluation result does not depend on any lower-bound condition
42 * being reached before the condition is evaluated to true again.
43 *
44 * Buffer usage conditions have the following properties:
45 * - the exact name of the session in which the channel to be monitored is
46 * defined,
47 * - the domain of the channel to be monitored,
48 * - the exact name of the channel to be monitored,
49 * - a usage threshold, expressed either in bytes or as a fraction of total
50 * buffer capacity.
51 *
52 * Wildcards, regular expressions or other globbing mechanisms are not supported
53 * in buffer usage condition properties.
54 */
55
56 /*
57 * Create a newly allocated lower-bound buffer usage condition.
58 *
59 * A lower-bound buffer usage condition evaluates to true whenever
60 * a buffer's usage _crosses_ the bound that is defined as part of the
61 * condition's properties from high to low. In other words, the condition only
62 * evaluates to true when a buffer's usage transitions from a value higher than
63 * the threshold defined in the condition to a value lower than the threshold
64 * defined in the condition.
65 *
66 * Returns a new condition on success, NULL on failure. This condition must be
67 * destroyed using lttng_condition_destroy().
68 */
69 extern struct lttng_condition *
70 lttng_condition_buffer_usage_low_create(void);
71
72 /*
73 * Create a newly allocated upper-bound buffer usage condition.
74 *
75 * An upper-bound buffer usage condition evaluates to true whenever
76 * a buffer's usage _crosses_ the bound that is defined as part of the
77 * condition's properties from low to high. In other words, the condition only
78 * evaluates to true when a buffer's usage transitions from a value lower than
79 * the threshold defined in the condition to a value higher than the threshold
80 * defined in the condition.
81 *
82 * Returns a new condition on success, NULL on failure. This condition must be
83 * destroyed using lttng_condition_destroy().
84 */
85 extern struct lttng_condition *
86 lttng_condition_buffer_usage_high_create(void);
87
88 /*
89 * Get the buffer usage threshold ratio of a buffer usage condition.
90 *
91 * The buffer usage condition's threshold must have been defined as a ratio in
92 * order for this call to succeed.
93 *
94 * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
95 * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
96 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
97 * expressed as a ratio of total buffer capacity, was not set prior to this
98 * call.
99 */
100 extern enum lttng_condition_status
101 lttng_condition_buffer_usage_get_threshold_ratio(
102 const struct lttng_condition *condition,
103 double *threshold_ratio);
104
105 /*
106 * Set the buffer usage threshold ratio of a buffer usage condition.
107 *
108 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
109 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
110 * either as a ratio or as an absolute size in bytes will override any
111 * previously set threshold.
112 *
113 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
114 * if invalid paramenters are passed.
115 */
116 extern enum lttng_condition_status
117 lttng_condition_buffer_usage_set_threshold_ratio(
118 struct lttng_condition *condition,
119 double threshold_ratio);
120
121 /*
122 * Get the buffer usage threshold of a buffer usage condition.
123 *
124 * The buffer usage condition's threshold must have been defined as an absolute
125 * value expressed in bytes in order for this call to succeed.
126 *
127 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
128 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
129 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
130 * bytes, was not set prior to this call.
131 */
132 extern enum lttng_condition_status
133 lttng_condition_buffer_usage_get_threshold(
134 const struct lttng_condition *condition,
135 uint64_t *threshold_bytes);
136
137 /*
138 * Set the buffer usage threshold in bytes of a buffer usage condition.
139 *
140 * Setting a threshold, either as a ratio or as an absolute size in bytes
141 * will override any previously set threshold.
142 *
143 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
144 * if invalid paramenters are passed.
145 */
146 extern enum lttng_condition_status
147 lttng_condition_buffer_usage_set_threshold(
148 struct lttng_condition *condition,
149 uint64_t threshold_bytes);
150
151 /*
152 * Get the session name property of a buffer usage condition.
153 *
154 * The caller does not assume the ownership of the returned session name. The
155 * session name shall only only be used for the duration of the condition's
156 * lifetime, or before a different session name is set.
157 *
158 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
159 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
160 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
161 * was not set prior to this call.
162 */
163 extern enum lttng_condition_status
164 lttng_condition_buffer_usage_get_session_name(
165 const struct lttng_condition *condition,
166 const char **session_name);
167
168 /*
169 * Set the session name property of a buffer usage condition.
170 *
171 * The passed session name parameter will be copied to the condition.
172 *
173 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
174 * if invalid paramenters are passed.
175 */
176 extern enum lttng_condition_status
177 lttng_condition_buffer_usage_set_session_name(
178 struct lttng_condition *condition,
179 const char *session_name);
180
181 /*
182 * Get the channel name property of a buffer usage condition.
183 *
184 * The caller does not assume the ownership of the returned channel name. The
185 * channel name shall only only be used for the duration of the condition's
186 * lifetime, or before a different channel name is set.
187 *
188 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
189 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
190 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
191 * was not set prior to this call.
192 */
193 extern enum lttng_condition_status
194 lttng_condition_buffer_usage_get_channel_name(
195 const struct lttng_condition *condition,
196 const char **channel_name);
197
198 /*
199 * Set the channel name property of a buffer usage condition.
200 *
201 * The passed channel name parameter will be copied to the condition.
202 *
203 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
204 * if invalid paramenters are passed.
205 */
206 extern enum lttng_condition_status
207 lttng_condition_buffer_usage_set_channel_name(
208 struct lttng_condition *condition,
209 const char *channel_name);
210
211 /*
212 * Get the domain type property of a buffer usage condition.
213 *
214 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
215 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
216 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
217 * call.
218 */
219 extern enum lttng_condition_status
220 lttng_condition_buffer_usage_get_domain_type(
221 const struct lttng_condition *condition,
222 enum lttng_domain_type *type);
223
224 /*
225 * Set the domain type property of a buffer usage condition.
226 *
227 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
228 * if invalid paramenters are passed.
229 */
230 extern enum lttng_condition_status
231 lttng_condition_buffer_usage_set_domain_type(
232 struct lttng_condition *condition,
233 enum lttng_domain_type type);
234
235
236 /**
237 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
238 * allow users to query a number of properties resulting from the evaluation
239 * of a condition which evaluated to true.
240 *
241 * The evaluation of a buffer usage condition yields two different results:
242 * - the usage ratio of the channel buffers at the time of the evaluation,
243 * - the usage, in bytes, of the channel buffers at the time of evaluation.
244 */
245
246 /*
247 * Get the buffer usage ratio property of a buffer usage evaluation.
248 *
249 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
250 * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
251 * an invalid parameter is passed.
252 */
253 extern enum lttng_evaluation_status
254 lttng_evaluation_buffer_usage_get_usage_ratio(
255 const struct lttng_evaluation *evaluation,
256 double *usage_ratio);
257
258 /*
259 * Get the buffer usage property of a buffer usage evaluation.
260 *
261 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
262 * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
263 */
264 extern enum lttng_evaluation_status
265 lttng_evaluation_buffer_usage_get_usage(
266 const struct lttng_evaluation *evaluation,
267 uint64_t *usage_bytes);
268
269 #ifdef __cplusplus
270 }
271 #endif
272
273 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
This page took 0.051646 seconds and 4 git commands to generate.