counter(3tcl) Counters and Histograms counter(3tcl)
______________________________________________________________________________
NAME
counter - Procedures for counters and histograms
SYNOPSIS
package require Tcl 8
package require counter ?2.0.4?
::counter::init tag args
::counter::count tag ?delta? ?instance?
::counter::start tag instance
::counter::stop tag instance
::counter::get tag args
::counter::exists tag
::counter::names
::counter::histHtmlDisplay tag args
::counter::reset tag args
______________________________________________________________________________
DESCRIPTION
The counter package provides a counter facility and can compute statis-
tics and histograms over the collected data.
::counter::init tag args
This defines a counter with the name tag. The args determines
the characteristics of the counter. The args are
-group name
Keep a grouped counter where the name of the histogram
bucket is passed into ::counter::count.
-hist bucketsize
Accumulate the counter into histogram buckets of size
bucketsize. For example, if the samples are millisecond
time values and bucketsize is 10, then each histogram
bucket represents time values of 0 to 10 msec, 10 to 20
msec, 20 to 30 msec, and so on.
-hist2x bucketsize
Accumulate the statistic into histogram buckets. The
size of the first bucket is bucketsize, each other bucket
holds values 2 times the size of the previous bucket.
For example, if bucketsize is 10, then each histogram
bucket represents time values of 0 to 10 msec, 10 to 20
msec, 20 to 40 msec, 40 to 80 msec, and so on.
-hist10x bucketsize
Accumulate the statistic into histogram buckets. The
size of the first bucket is bucketsize, each other bucket
holds values 10 times the size of the previous bucket.
For example, if bucketsize is 10, then each histogram
bucket represents time values of 0 to 10 msec, 10 to 100
msec, 100 to 1000 msec, and so on.
-lastn N
Save the last N values of the counter to maintain a "run-
ning average" over the last N values.
-timehist secsPerMinute
Keep a time-based histogram. The counter is summed into
a histogram bucket based on the current time. There are
60 per-minute buckets that have a size determined by sec-
sPerMinute, which is normally 60, but for testing pur-
poses can be less. Every "hour" (i.e., 60 "minutes") the
contents of the per-minute buckets are summed into the
next hourly bucket. Every 24 "hours" the contents of the
per-hour buckets are summed into the next daily bucket.
The counter package keeps all time-based histograms in
sync, so the first secsPerMinute value seen by the pack-
age is used for all subsequent time-based histograms.
::counter::count tag ?delta? ?instance?
Increment the counter identified by tag. The default increment
is 1, although you can increment by any value, integer or real,
by specifying delta. You must declare each counter with
::counter::init to define the characteristics of counter before
you start to use it. If the counter type is -group, then the
counter identified by instance is incremented.
::counter::start tag instance
Record the starting time of an interval. The tag is the name of
the counter defined as a -hist value-based histogram. The in-
stance is used to distinguish this interval from any other in-
tervals that might be overlapping this one.
::counter::stop tag instance
Record the ending time of an interval. The delta time since the
corresponding ::counter::start call for instance is recorded in
the histogram identified by tag.
::counter::get tag args
Return statistics about a counter identified by tag. The args
determine what value to return:
-total Return the total value of the counter. This is the de-
fault if args is not specified.
-totalVar
Return the name of the total variable. Useful for speci-
fying with -textvariable in a Tk widget.
-N Return the number of samples accumulated into the
counter.
-avg Return the average of samples accumulated into the
counter.
-avgn Return the average over the last N samples taken. The N
value is set in the ::counter::init call.
-hist bucket
If bucket is specified, then the value in that bucket of
the histogram is returned. Otherwise the complete his-
togram is returned in array get format sorted by bucket.
-histVar
Return the name of the histogram array variable.
-histHour
Return the complete hourly histogram in array get format
sorted by bucket.
-histHourVar
Return the name of the hourly histogram array variable.
-histDay
Return the complete daily histogram in array get format
sorted by bucket.
-histDayVar
Return the name of the daily histogram array variable.
-resetDate
Return the clock seconds value recorded when the counter
was last reset.
-all Return an array get of the array used to store the
counter. This includes the total, the number of samples
(N), and any type-specific information. This does not
include the histogram array.
::counter::exists tag
Returns 1 if the counter is defined.
::counter::names
Returns a list of all counters defined.
::counter::histHtmlDisplay tag args
Generate HTML to display a histogram for a counter. The args
control the format of the display. They are:
-title string
Label to display above bar chart
-unit unit
Specify minutes, hours, or days for the time-base his-
tograms. For value-based histograms, the unit is used in
the title.
-images url
URL of /images directory.
-gif filename
Image for normal histogram bars. The filename is rela-
tive to the -images directory.
-ongif filename
Image for the active histogram bar. The filename is rel-
ative to the -images directory.
-max N Maximum number of value-based buckets to display.
-height N
Pixel height of the highest bar.
-width N
Pixel width of each bar.
-skip N
Buckets to skip when labeling value-based histograms.
-format string
Format used to display labels of buckets.
-text boolean
If 1, a text version of the histogram is dumped, other-
wise a graphical one is generated.
::counter::reset tag args
Resets the counter with the name tag to an initial state. The
args determine the new characteristics of the counter. They have
the same meaning as described for ::counter::init.
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category counter of
the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
also report any ideas for enhancements you may have for either package
and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
KEYWORDS
counting, histogram, statistics, tallying
CATEGORY
Data structures
tcllib 2.0.4 counter(3tcl)