timehist.h revision 356345 
1/*
2 * util/timehist.h - make histogram of time values.
3 *
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
5 *
6 * This software is open source.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 *
15 * Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * Neither the name of the NLNET LABS nor the names of its contributors may
20 * be used to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 */
35
36/**
37 * \file
38 *
39 * This file contains functions to make a histogram of time values.
40 */
41
42#ifndef UTIL_TIMEHIST_H
43#define UTIL_TIMEHIST_H
44
45/** Number of buckets in a histogram */
46#define NUM_BUCKETS_HIST 40
47
48/**
49 * Bucket of time history information
50 */
51struct th_buck {
52	/** lower bound */
53	struct timeval lower;
54	/** upper bound */
55	struct timeval upper;
56	/** number of items */
57	size_t count;
58};
59
60/**
61 * Keep histogram of time values.
62 */
63struct timehist {
64	/** number of buckets */
65	size_t num;
66	/** bucket array */
67	struct th_buck* buckets;
68};
69
70/**
71 * Setup a histogram, default
72 * @return histogram or NULL on malloc failure.
73 */
74struct timehist* timehist_setup(void);
75
76/**
77 * Delete histogram
78 * @param hist: to delete
79 */
80void timehist_delete(struct timehist* hist);
81
82/**
83 * Clear histogram
84 * @param hist: to clear all data from
85 */
86void timehist_clear(struct timehist* hist);
87
88/**
89 * Add time value to histogram.
90 * @param hist: histogram
91 * @param tv: time value
92 */
93void timehist_insert(struct timehist* hist, struct timeval* tv);
94
95/**
96 * Find time value for given quartile, such as 0.25, 0.50, 0.75.
97 * The looks up the value for the i-th element in the sorted list of time
98 * values, as approximated using the histogram.
99 * @param hist: histogram. Interpolated information is used from it.
100 * @param q: quartile, 0.50 results in the median. Must be >0 and <1.
101 * @return: the time in seconds for that percentage.
102 */
103double timehist_quartile(struct timehist* hist, double q);
104
105/**
106 * Printout histogram
107 * @param hist: histogram
108 */
109void timehist_print(struct timehist* hist);
110
111/**
112 * Log histogram, print it to the logfile.
113 * @param hist: histogram
114 * @param name: the name of the value column
115 */
116void timehist_log(struct timehist* hist, const char* name);
117
118/**
119 * Export histogram to an array.
120 * @param hist: histogram
121 * @param array: the array to export to.
122 * @param sz: number of items in array.
123 */
124void timehist_export(struct timehist* hist, long long* array, size_t sz);
125
126/**
127 * Import histogram from an array.
128 * @param hist: histogram
129 * @param array: the array to import from.
130 * @param sz: number of items in array.
131 */
132void timehist_import(struct timehist* hist, long long* array, size_t sz);
133
134#endif /* UTIL_TIMEHIST_H */
135