1139825Simp/* 254134Swpaul * util/timehist.h - make histogram of time values. 354134Swpaul * 454134Swpaul * Copyright (c) 2007, NLnet Labs. All rights reserved. 554134Swpaul * 654134Swpaul * This software is open source. 754134Swpaul * 854134Swpaul * Redistribution and use in source and binary forms, with or without 954134Swpaul * modification, are permitted provided that the following conditions 1054134Swpaul * are met: 1154134Swpaul * 1254134Swpaul * Redistributions of source code must retain the above copyright notice, 1354134Swpaul * this list of conditions and the following disclaimer. 1454134Swpaul * 1554134Swpaul * Redistributions in binary form must reproduce the above copyright notice, 1654134Swpaul * this list of conditions and the following disclaimer in the documentation 1754134Swpaul * and/or other materials provided with the distribution. 1854134Swpaul * 1954134Swpaul * Neither the name of the NLNET LABS nor the names of its contributors may 2054134Swpaul * be used to endorse or promote products derived from this software without 2154134Swpaul * specific prior written permission. 2254134Swpaul * 2354134Swpaul * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 2454134Swpaul * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2554134Swpaul * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 2654134Swpaul * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 2754134Swpaul * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 2854134Swpaul * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 2954134Swpaul * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 3054134Swpaul * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 3154134Swpaul * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 3254134Swpaul * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 3354134Swpaul * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3454134Swpaul */ 3554134Swpaul 3654134Swpaul/** 3754134Swpaul * \file 3854134Swpaul * 3954134Swpaul * This file contains functions to make a histogram of time values. 4054134Swpaul */ 4154134Swpaul 4254134Swpaul#ifndef UTIL_TIMEHIST_H 4354134Swpaul#define UTIL_TIMEHIST_H 4454134Swpaul 4554134Swpaul/** Number of buckets in a histogram */ 4654134Swpaul#define NUM_BUCKETS_HIST 40 4754134Swpaul 4854134Swpaul/** 4954134Swpaul * Bucket of time history information 5054134Swpaul */ 5154134Swpaulstruct th_buck { 5254134Swpaul /** lower bound */ 5354134Swpaul struct timeval lower; 5454134Swpaul /** upper bound */ 5567314Sjon struct timeval upper; 5654134Swpaul /** number of items */ 5754134Swpaul size_t count; 5854134Swpaul}; 5954134Swpaul 6054134Swpaul/** 6154134Swpaul * Keep histogram of time values. 6254134Swpaul */ 6354134Swpaulstruct timehist { 6454134Swpaul /** number of buckets */ 6554134Swpaul size_t num; 6654134Swpaul /** bucket array */ 6754134Swpaul struct th_buck* buckets; 6854134Swpaul}; 6954134Swpaul 7054134Swpaul/** 7154134Swpaul * Setup a histogram, default 7254134Swpaul * @return histogram or NULL on malloc failure. 7354134Swpaul */ 7454134Swpaulstruct timehist* timehist_setup(void); 75201430Smbr 7654134Swpaul/** 7754134Swpaul * Delete histogram 7854134Swpaul * @param hist: to delete 7967314Sjon */ 8082978Swpaulvoid timehist_delete(struct timehist* hist); 8154134Swpaul 8254134Swpaul/** 8354134Swpaul * Clear histogram 8454134Swpaul * @param hist: to clear all data from 8554134Swpaul */ 8654134Swpaulvoid timehist_clear(struct timehist* hist); 8754134Swpaul 8854134Swpaul/** 89201430Smbr * Add time value to histogram. 9054134Swpaul * @param hist: histogram 9154134Swpaul * @param tv: time value 9254134Swpaul */ 9354134Swpaulvoid timehist_insert(struct timehist* hist, struct timeval* tv); 94201430Smbr 9554134Swpaul/** 9654134Swpaul * Find time value for given quartile, such as 0.25, 0.50, 0.75. 9754134Swpaul * The looks up the value for the i-th element in the sorted list of time 9867314Sjon * values, as approximated using the histogram. 9982978Swpaul * @param hist: histogram. Interpolated information is used from it. 10054134Swpaul * @param q: quartile, 0.50 results in the median. Must be >0 and <1. 10154134Swpaul * @return: the time in seconds for that percentage. 10254134Swpaul */ 10354134Swpauldouble timehist_quartile(struct timehist* hist, double q); 10466681Swpaul 10554134Swpaul/** 10654134Swpaul * Printout histogram 10754134Swpaul * @param hist: histogram 10854134Swpaul */ 10954134Swpaulvoid timehist_print(struct timehist* hist); 11054134Swpaul 11154134Swpaul/** 11254134Swpaul * Log histogram, print it to the logfile. 11354134Swpaul * @param hist: histogram 11454134Swpaul * @param name: the name of the value column 11554134Swpaul */ 11654134Swpaulvoid timehist_log(struct timehist* hist, const char* name); 11754134Swpaul 11854134Swpaul/** 11954134Swpaul * Export histogram to an array. 12054134Swpaul * @param hist: histogram 12154134Swpaul * @param array: the array to export to. 12254134Swpaul * @param sz: number of items in array. 12354134Swpaul */ 12454134Swpaulvoid timehist_export(struct timehist* hist, long long* array, size_t sz); 12554134Swpaul 12654134Swpaul/** 12754134Swpaul * Import histogram from an array. 12854134Swpaul * @param hist: histogram 12954134Swpaul * @param array: the array to import from. 13054134Swpaul * @param sz: number of items in array. 13154134Swpaul */ 13254134Swpaulvoid timehist_import(struct timehist* hist, long long* array, size_t sz); 13354134Swpaul 13454134Swpaul#endif /* UTIL_TIMEHIST_H */ 13554134Swpaul