aboutsummaryrefslogtreecommitdiffstats
path: root/lib/librte_jobstats/rte_jobstats.h
blob: c2b285f878f1ffcaba97b1b8d8da52f9f929e5f1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
/*-
 *   BSD LICENSE
 *
 *   Copyright(c) 2015 Intel Corporation. All rights reserved.
 *   All rights reserved.
 *
 *   Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *   are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in
 *       the documentation and/or other materials provided with the
 *       distribution.
 *     * Neither the name of Intel Corporation nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 *
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef JOBSTATS_H_
#define JOBSTATS_H_

#include <stdint.h>

#include <rte_memory.h>
#include <rte_memcpy.h>

#ifdef __cplusplus
extern "C" {
#endif

#define RTE_JOBSTATS_NAMESIZE 32

/* Forward declarations. */
struct rte_jobstats_context;
struct rte_jobstats;

/**
 * This function should calculate new period and set it using
 * rte_jobstats_set_period() function. Time spent in this function will be
 * added to job's runtime.
 *
 * @param job
 *  The job data structure handler.
 * @param job_result
 *  Result of calling job callback.
 */
typedef void (*rte_job_update_period_cb_t)(struct rte_jobstats *job,
		int64_t job_result);

struct rte_jobstats {
	uint64_t period;
	/**< Estimated period of execution. */

	uint64_t min_period;
	/**< Minimum period. */

	uint64_t max_period;
	/**< Maximum period. */

	int64_t target;
	/**< Desired value for this job. */

	rte_job_update_period_cb_t update_period_cb;
	/**< Period update callback. */

	uint64_t exec_time;
	/**< Total time (sum) that this job was executing. */

	uint64_t min_exec_time;
	/**< Minimum execute time. */

	uint64_t max_exec_time;
	/**< Minimum execute time. */

	uint64_t exec_cnt;
	/**< Execute count. */

	char name[RTE_JOBSTATS_NAMESIZE];
	/**< Name of this job */

	struct rte_jobstats_context *context;
	/**< Job stats context object that is executing this job. */
} __rte_cache_aligned;

struct rte_jobstats_context {
	/** Viariable holding time at different points:
	 * -# loop start time if loop was started but no job executed yet.
	 * -# job start time if job is currently executing.
	 * -# job finish time if job finished its execution.
	 * -# loop finish time if loop finished its execution. */
	uint64_t state_time;

	uint64_t loop_executed_jobs;
	/**< Count of executed jobs in this loop. */

	/* Statistics start. */

	uint64_t exec_time;
	/**< Total time taken to execute jobs, not including management time. */

	uint64_t min_exec_time;
	/**< Minimum loop execute time. */

	uint64_t max_exec_time;
	/**< Minimum loop execute time. */

	/**
	 * Sum of time that is not the execute time (ex: from job finish to next
	 * job start).
	 *
	 * This time might be considered as overhead of library + job scheduling.
	 */
	uint64_t management_time;

	uint64_t min_management_time;
	/**< Minimum management time */

	uint64_t max_management_time;
	/**< Maximum management time */

	uint64_t start_time;
	/**< Time since last reset stats. */

	uint64_t job_exec_cnt;
	/**< Total count of executed jobs. */

	uint64_t loop_cnt;
	/**< Total count of executed loops with at least one executed job. */
} __rte_cache_aligned;

/**
 * Initialize given context object with default values.
 *
 * @param ctx
 *  Job stats context object to initialize.
 *
 * @return
 *  0 on success
 *  -EINVAL if *ctx* is NULL
 */
int
rte_jobstats_context_init(struct rte_jobstats_context *ctx);

/**
 * Mark that new set of jobs start executing.
 *
 * @param ctx
 *  Job stats context object.
 */
void
rte_jobstats_context_start(struct rte_jobstats_context *ctx);

/**
 * Mark that there is no more jobs ready to execute in this turn. Calculate
 * stats for this loop turn.
 *
 * @param ctx
 *  Job stats context.
 */
void
rte_jobstats_context_finish(struct rte_jobstats_context *ctx);

/**
 * Function resets job context statistics.
 *
 * @param ctx
 *  Job stats context which statistics will be reset.
 */
void
rte_jobstats_context_reset(struct rte_jobstats_context *ctx);

/**
 * Initialize given job stats object.
 *
 * @param job
 *  Job object.
 * @param name
 *  Optional job name.
 * @param min_period
 *  Minimum period that this job can accept.
 * @param max_period
 *  Maximum period that this job can accept.
 * @param initial_period
 *  Initial period. It will be checked against *min_period* and *max_period*.
 * @param target
 *  Target value that this job try to achieve.
 *
 * @return
 *  0 on success
 *  -EINVAL if *job* is NULL
 */
int
rte_jobstats_init(struct rte_jobstats *job, const char *name,
		uint64_t min_period, uint64_t max_period, uint64_t initial_period,
		int64_t target);

/**
 * Set job desired target value. Difference between target and job value
 * value must be used to properly adjust job execute period value.
 *
 * @param job
 *  The job object.
 * @param target
 *  New target.
 */
void
rte_jobstats_set_target(struct rte_jobstats *job, int64_t target);

/**
 * Mark that *job* is starting of its execution in context of *ctx* object.
 *
 * @param ctx
 *  Job stats context.
 * @param job
 *  Job object.
 * @return
 *  0 on success
 *  -EINVAL if *ctx* or *job* is NULL or *job* is executing in another context
 *  context already,
 */
int
rte_jobstats_start(struct rte_jobstats_context *ctx, struct rte_jobstats *job);

/**
 * Mark that *job* finished its execution, but time of this work will be skipped
 * and added to management time.
 *
 * @param job
 *  Job object.
 *
 * @return
 *  0 on success
 *  -EINVAL if job is NULL or job was not started (it have no context).
 */
int
rte_jobstats_abort(struct rte_jobstats *job);

/**
 * Mark that *job* finished its execution. Context in which it was executing
 * will receive stat update. After this function call *job* object is ready to
 * be executed in other context.
 *
 * @param job
 *  Job object.
 * @param job_value
 *  Job value. Job should pass in this parameter a value that it try to optimize
 *  for example the number of packets it processed.
 *
 * @return
 *  0 if job's period was not updated (job target equals *job_value*)
 *  1 if job's period was updated
 *  -EINVAL if job is NULL or job was not started (it have no context).
 */
int
rte_jobstats_finish(struct rte_jobstats *job, int64_t job_value);

/**
 * Set execute period of given job.
 *
 * @param job
 *  The job object.
 * @param period
 *  New period value.
 * @param saturate
 *  If zero, skip period saturation to min, max range.
 */
void
rte_jobstats_set_period(struct rte_jobstats *job, uint64_t period,
		uint8_t saturate);
/**
 * Set minimum execute period of given job. Current period will be checked
 * against new minimum value.
 *
 * @param job
 *  The job object.
 * @param period
 *  New minimum period value.
 */
void
rte_jobstats_set_min(struct rte_jobstats *job, uint64_t period);
/**
 * Set maximum execute period of given job. Current period will be checked
 * against new maximum value.
 *
 * @param job
 *  The job object.
 * @param period
 *  New maximum period value.
 */
void
rte_jobstats_set_max(struct rte_jobstats *job, uint64_t period);

/**
 * Set update period callback that is invoked after job finish.
 *
 * If application wants to do more sophisticated calculations than default
 * it can provide this handler.
 *
 * @param job
 *  Job object.
 * @param update_pedriod_cb
 *  Callback to set. If NULL restore default update function.
 */
void
rte_jobstats_set_update_period_function(struct rte_jobstats *job,
		rte_job_update_period_cb_t update_period_cb);

/**
 * Function resets job statistics.
 *
 * @param job
 *  Job which statistics will be reset.
 */
void
rte_jobstats_reset(struct rte_jobstats *job);

#ifdef __cplusplus
}
#endif

#endif /* JOBSTATS_H_ */