[hipl-commit] [trunk] Rev 3781: Doxygen for hip_statistics.*
- From: Tobias Heer <heer@xxxxxxxxxxxxxxxxx>
- To: hipl-commit@xxxxxxxxxxxxx
- Date: Wed, 3 Mar 2010 16:56:44 +0200
Committer: Tobias Heer <heer@xxxxxxxxxxxxxxxxx>
Date: Wed Mar 03 15:56:42 2010 +0100
Revision: 3781
Revision-id: heer@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk
Log:
Doxygen for hip_statistics.*
Modified:
D lib/core/hip_statistics.c.doxyme
D lib/core/hip_statistics.h.doxyme
M lib/core/hip_statistics.c
M lib/core/hip_statistics.h
=== modified file 'lib/core/hip_statistics.c'
--- lib/core/hip_statistics.c 2010-02-10 23:55:24 +0000
+++ lib/core/hip_statistics.c 2010-03-03 14:56:42 +0000
@@ -1,8 +1,24 @@
+/** @file hip_statistics.c
+ *
+ * Distributed under <a href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>
+ *
+ * This file defines helper function for statistical computations
+ *
+ * @author Rene Hummen
+ */
+
#include <math.h>
#include "hip_statistics.h"
#include "debug.h"
+/**
+ * Convert a timeval struct to milliseconds
+ *
+ *
+ * @param timeval time value
+ * @return time value in milliseconds
+ */
static uint64_t timeval_to_uint64(const struct timeval *timeval)
{
HIP_ASSERT(timeval != NULL);
@@ -11,6 +27,13 @@
return (timeval->tv_sec * STATS_IN_USECS) + timeval->tv_usec;
}
+/**
+ * Compute mean value for a given data set
+ *
+ * @param statistics_data data set
+ * @param scaling_factor scale samples by this constant factor
+ * @return mean value
+ */
static double calc_avg(const statistics_data_t *statistics_data,
const double scaling_factor)
{
@@ -27,6 +50,13 @@
return avg;
}
+/**
+ * Compute standard deviation for a given data set
+ *
+ * @param statistics_data data set
+ * @param scaling_factor scale samples by this constant factor
+ * @return standard deviation
+ */
static double calc_std_dev(const statistics_data_t *statistics_data,
const double scaling_factor)
{
@@ -46,6 +76,13 @@
return std_dev / scaling_factor;
}
+/**
+ * Compute the difference between two timevals
+ *
+ * @param timeval_start first time value
+ * @param timeval_end second time valie
+ * @return difference in microseconds
+ */
uint64_t calc_timeval_diff(const struct timeval *timeval_start,
const struct timeval *timeval_end)
{
@@ -68,6 +105,16 @@
return timeval_to_uint64(&rel_timeval);
}
+/**
+ * Adds a sample to a given data set
+ *
+ * @note Memory for statistics_data must be allocated
+ * and managed outside this function.
+ *
+ * @param statistics_data data set
+ * @param item_value sample
+ * @return 0 on success, -1 otherwise
+ */
int add_statistics_item(statistics_data_t *statistics_data,
const uint64_t item_value)
{
@@ -111,7 +158,18 @@
return err;
}
-/* only returns values for non-NULL pointers */
+/**
+ * Fills a set of pointers with the results present in a given
+ * data structure
+ *
+ * @param statistics_data data set
+ * @param num_items[out] number of samples in the data set
+ * @param min[out] minimal value in the data set
+ * @param max[out] maximal value in the data set
+ * @param avg[out] mean value of the data set
+ * @param std_dev[out] standard deviation from the mean value
+ * @param scaling_factor scale values by this constant factor
+ */
void calc_statistics(const statistics_data_t *statistics_data,
uint32_t *num_items,
double *min,
=== modified file 'lib/core/hip_statistics.h'
--- lib/core/hip_statistics.h 2010-02-17 13:08:39 +0000
+++ lib/core/hip_statistics.h 2010-03-03 14:56:42 +0000
@@ -1,3 +1,11 @@
+/** @file hip_statistics.h
+ *
+ * Distributed under <a href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>
+ *
+ * Header file for hip_statistics.c
+ *
+ * @author Rene Hummen
+ */
#ifndef HIP_LIB_CORE_HIP_STATISTICS_H
#define HIP_LIB_CORE_HIP_STATISTICS_H
@@ -8,12 +16,15 @@
#define STATS_IN_MSECS 1000
#define STATS_IN_USECS 1000000
+/**
+ * Data set that contains the the collected values
+ */
typedef struct statistics_data {
- uint32_t num_items;
- uint64_t added_values;
- uint64_t added_squared_values;
- uint64_t min_value;
- uint64_t max_value;
+ uint32_t num_items; /* number of items that have been added to
the set */
+ uint64_t added_values; /* total amount of added values */
+ uint64_t added_squared_values; /* squared values for standard deviation
calculation */
+ uint64_t min_value; /* minimal of all values added to the set
*/
+ uint64_t max_value; /* maximum of all values added to the set
*/
} statistics_data_t;
uint64_t calc_timeval_diff(const struct timeval *timeval_start,
Other related posts:
- » [hipl-commit] [trunk] Rev 3781: Doxygen for hip_statistics.* - Tobias Heer
