/tmp/l4check/full_tree/trunk/l4/pkg/rt_mon/include/histogram.h File Reference

Some functions to work with histograms. More...

#include <l4/sys/compiler.h>
#include <l4/rt_mon/types.h>

Go to the source code of this file.

Functions
EXTERN_C_BEGIN rt_mon_histogram_t *	rt_mon_hist_create (double low, double high, int bins, const char *name, const char *unit_abs, const char *unit_ord, int clock)
	Creates a new histogram, allocates memory for it and registers it at the coordinator.
void	rt_mon_hist_insert_data (rt_mon_histogram_t *hist, rt_mon_time_t x, unsigned int val)
	Inserts an amount into the histogram.
void	rt_mon_hist_insert_data_int (rt_mon_histogram_t *hist, rt_mon_time_t x, unsigned int val)
	Inserts an amount into the histogram, integer version.
void	rt_mon_hist_insert_lost (rt_mon_histogram_t *hist, unsigned int count)
	Take note of lost data points.
int	rt_mon_hist_get_data (rt_mon_histogram_t *hist, rt_mon_time_t x)
	Get a data point from a histogram.
void	rt_mon_hist_free (rt_mon_histogram_t *hist)
	Destroys a histogram, unregisters it at the coordinator and frees its memory.
void	rt_mon_hist_reset (rt_mon_histogram_t *hist)
	completely re-initialize histogram
void	rt_mon_hist_dump (rt_mon_histogram_t *hist)
	Dump the content of a histogram using printf.
void	rt_mon_hist_start (rt_mon_histogram_t *hist)
	Set start point in time for a duration measurement.
void	rt_mon_hist_end (rt_mon_histogram_t *hist)
	Set end point in time for a duration measurement, insert resulting duration into the histogram.
rt_mon_time_t	rt_mon_hist_measure (rt_mon_histogram_t *hist)
	Get a current time stamp for a histogram.
double	rt_mon_hist_avg (rt_mon_histogram_t *hist)
	Compute the average value for a histogram.

---

Detailed Description

Some functions to work with histograms.

Date:

08/20/2004

Author:

Martin Pohlack <mp26@os.inf.tu-dresden.de>

---

Function Documentation

double rt_mon_hist_avg

(

rt_mon_histogram_t *

hist

)

Compute the average value for a histogram.

Parameters:

hist

histogram to operate on

Returns:

average value for the histogram

EXTERN_C_BEGIN rt_mon_histogram_t* rt_mon_hist_create	(	double	low,
		double	high,
		int	bins,
		const char *	name,
		const char *	unit_abs,
		const char *	unit_ord,
		int	clock
	)

Creates a new histogram, allocates memory for it and registers it at the coordinator.

Parameters:

	low	lower bound for histogram
	high	upper bound for histogram
	bins	number of bins to use between low and high
	name	the name of this histogram
	unit_abs	measurement unit for the abscissa
	unit_ord	measurement unit for the ordinate
	clock	type of time source to use for this sensor

Returns:

pointer to newly malloc'ed, registered and initialized histogram, otherwise

• NULL in case of error (like out of memory)

void rt_mon_hist_dump

(

rt_mon_histogram_t *

hist

)

Dump the content of a histogram using printf.

Parameters:

hist

histogram to dump

void rt_mon_hist_end

(

rt_mon_histogram_t *

hist

)

[inline]

Set end point in time for a duration measurement, insert resulting duration into the histogram.

Parameters:

hist

histogram to operate on

void rt_mon_hist_free

(

rt_mon_histogram_t *

hist

)

Destroys a histogram, unregisters it at the coordinator and frees its memory.

Parameters:

hist

histogram to free

int rt_mon_hist_get_data	(	rt_mon_histogram_t *	hist,
		rt_mon_time_t	x
	)			[inline]

Get a data point from a histogram.

Parameters:

	hist	histogram to get data from
	x	point to get data from

Returns:

value from histogram

void rt_mon_hist_insert_data	(	rt_mon_histogram_t *	hist,
		rt_mon_time_t	x,
		unsigned int	val
	)

Inserts an amount into the histogram.

Parameters:

	hist	histogram to insert data to
	x	point on the abscissa
	val	value to add to the specified point

void rt_mon_hist_insert_data_int	(	rt_mon_histogram_t *	hist,
		rt_mon_time_t	x,
		unsigned int	val
	)

Inserts an amount into the histogram, integer version.

This function behaves like rt_mon_hist_insert_data(), but uses only integer operations internally.

Bug:

for non-integer lower bounds, the bin needs an additional offset, which is not implemented as of today.

void rt_mon_hist_insert_lost	(	rt_mon_histogram_t *	hist,
		unsigned int	count
	)

Take note of lost data points.

Parameters:

	hist	histogram to insert data to
	count	number of lost events

rt_mon_time_t rt_mon_hist_measure

(

rt_mon_histogram_t *

hist

)

[inline]

Get a current time stamp for a histogram.

Note:

The histogram is not modified.

Parameters:

hist

histogram to operate on

Returns:

measured time stamp

void rt_mon_hist_reset

(

rt_mon_histogram_t *

hist

)

completely re-initialize histogram

Reset all the collected date, i.e.:

• underflow and overflow counter
• current minimum and maximum
• accumulated sum and count
• histogram content itself

Parameters:

hist

histogram to reset

void rt_mon_hist_start

(

rt_mon_histogram_t *

hist

)

[inline]

Set start point in time for a duration measurement.

Parameters:

hist

histogram to operate on