Crate rustics

Expand description

Rustics provides a simple interface for recording sample and event streams and printing statistics.

Many of the module comments contain examples of usage. The main.rs program contains a brief example of how to use two of the statistics types.

§Types

Statistics for Integer Samples
- Integer statistics provide summary parameters, like the mean, and a pseudo-log histogram.
- Samples are of type i64.
- For the pseudo-log histogram, the log of a positive number is defined as the logarithm to the base 2, rounding up any fractional part. Therefore, the pseudo-log of 5 is 3. The pseudo-log of a negative number n is defines as -pseudo-log(-n), and the pseudo-log of 0 is defined as 0.
Basic Integer Statistics Types
- RunningInteger
  - RunningInteger implements running statistics for a series of sample values.
  - It also provides a pseudo-log histogram of the samples.
- IntegerWindow
  - IntegerWindow implements a fixed-size window of the last n samples recorded. Summary statistics of the window samples are computed on demand.
  - Like RunningInteger, it also provides a pseudo-log histogram. The histogram counts all samples seen, not just the current window.
- Counter
  - This type implements a simple counter that generates no further statistics. It can be used for counting events, for example.
Basic Time Statistics Types
- RunningTime
  - This type uses the RunningInteger code to handle time intervals. Values are printed using units of time when appropriate.
- TimeWindow
  - This type uses the IntegerWindow code to handle time intervals. As with the RunningTime type, values are printed in units of time.
Basic Floating Point Statistics Types
- Floating point samples currently are supported only for machines that use IEEE f64 format.
- RunningFloat
  - This type keeps running statistics, like RunningInteger. It uses a coarser pseudo-log function than the integer statistics. See FloatHistogram for details.
- FloatWindow
  - FloatWindow keeps a fixed-size window of samples, like IntegerWindow. It creates a histogram using FloatHistogram.
Hierarchical Statistics: The Hier Type
- A Hier instance uses multiple Rustics instances to maintain statistical information. This approach can reduce accuracy loss over long sample periods and provide historical data.
- Samples are collected into a single Rustics instance. When this instance has collected a configurable number of samples, it is pushed onto a list of historical data, and a new Rustics instance is created to collect the next batch of samples. This process repeats indefinitely.
- When this list has reached a configurable size limit, the oldest entry is discarded every time a new entry is pushed onto it.
- This list forms level 0 of the hierarchy.
- When a configurable number of level 0 instances have been collected, a summary instance of those instances is created and pushed onto level 1. Like level 0, level 1 forms a list with a configurable size limit.
- This process is performed recursively for a user-specified number of levels. The summed instances thus form a hierarchy somewhat like a tree or a forest of trees.
- Users can query any member of the hierarchy to look into the past.
- A Hier instance also can maintain an optional window of the last N samples collected to serve as the values for Rustics queries of the hierarchy as a whole. If the user does not configure a window, the current level 0 instance (the one receiving samples) is used.
- In addition to pushing a new level 0 instances after a fixed number of samples, the user instead can choose to push a new level zero instance by calling the advance() method, allowing for more application-specific control.
Hierarchical Statistics Types
- Hier
  - The Hier struct provides framework code for hierarchical statistics. After creating a Hier instance, most users will use this interface or the Rustics interface to interact with this type. For example, data is recorded into a Hier instance by invoking Rustics methods directly on the Hier instance itself.
  - The HierGenerator trait provides an interface for Hier to use a basic Rustics type like RunningInteger or RunningTime. Most users will not use this type directly.
- IntegerHier
  - This struct extends the RunningInteger type to support the Hier code. See IntegerHier::new_hier() for a simple interface to create a Hier instance using RunningInteger instances for statistics collection. The integer_hier and hier test modules also contains sample_usage() and make_hier() functions as examples.
- TimeHier
  - TimeHier implements Hier for the RunningTime type. TimeHier::new_hier() will make a Hier instance that uses RunningTime as the Rustics type.
- FloatHier
  - This struct extends the RunningFloat type to support the Hier code. See FloatHier::new_hier() for an interface to create a Hier instance. This type is very similar to IntegerHier.
Creating Sets
- The “arc_sets” and “rc_sets” modules implement sets that accept Rustics instances and other sets as members. Sets can be printed and cleared recursively by invoking a method on the topmost set.
- ArcSet
  - This type provides an Arc-based implementation that is thread-safe.
- RcSet
  - This type implements an Rc-based version of sets. These sets are faster than Arc-based sets, but are not thread-safe.
Timers
- Timer
  - This trait defines the basic abstract timer. A timer has a frequency and returns an integer duration in units of that frequency. The Timer interface provides start() and finish() methods to measure clock intervals.
- DurationTimer
  - This type is an implementation of Timer that uses the Rust “Duration” struct, which measures wall clock time.
- SimpleClock
  - This trait defines the interface used to query a user-defined clock, which can be wrapped using the ClockTimer type, q.v.
  - Clock values must be returned as a monotonically non-decreasing integer tick count.
  - The interface requires a hz() member to provide the clock frequency to the ClockTimer layer.
- ClockTimer
  - This Timer implementation is a wrapper for instances of trait SimpleClock. For example, a cycle counter like rdtsc on Intel could be wrapped to implement a ClockTimer.
Printing
- Printer
  - This trait defines the interface for printing Rustics instances, so it can be used to implement custom printers.
  - See StdioPrinter for a sample implementation. This type is used as the default printer to send output to stdout.
- Printable
  - The Printable type provides standard formatting for printing data and some support functions for more readable output, like time values scaled to human-understandable forms and integers with commas. It is of interest mostly to developers creating new Rustics implementations.

Modules§

arc_sets: Type
counter: Type
float_hier: Type
float_histogram: Type
float_window: Type
hier: Type
integer_hier: Type
integer_window: Type
log_histogram: Type
merge: Type
printable: Type
rc_sets: Type
running_float: Type
running_integer: Type
running_time: Type
sum
time: Types
time_hier: Type
time_window: Type
window: Type

Macros§

arc_box: Creates a shareable instance for an ArcSet item.
arc_item: Converts an ArcSet item into a Rustics or subset reference.
arc_item_mut: Converts an ArcSet item into a mutable Rustics or subset reference.
hier_box: Converts a Rustics instance in the shareable form for use by the Hier code.
hier_item: Converts a Hier member into a Rustics or subset reference.
hier_item_mut: Converts a Hier member into a mutable Rustics or subset reference.
printer: Converts a PrinterBox into a Printer reference.
printer_box: Converts a Printer instance into the shareable form.
printer_mut: Converts a PrinterBox into a mutable Printer reference.
rc_box: Creates a shareable instance of an RcSet item.
rc_item: Converts an RcSet member into a Rustics or subset reference.
rc_item_mut: Converts an RcSet member into a mutable Rustics or subset reference.
timer: Converts a TimerBox into a Timer reference.
timer_box: Converts a TimerBox instance into the shareable form, currently Rc<RefCell<dyn Timer>>.
timer_mut: Converts a TimerBox into a mutable Timer reference.

Structs§

EstimateData: Provides the data required to try to estimate the third moment about the mean.
ExportStats: Defines the data available from the Rustics export_stats() member, which returns bulk data.
PrintOpts: Defines the options available for printing.
RecoverData: Provides the data required to try to recover the sum of the squares and the sum of the fourth power of each of the data samples.
Statistics: Contains the return data for compute_statistics.
StatisticsData: Provides the data for estimating the second and fourth moments about the mean, as well as the mean itself.
StdioPrinter: The StdioPrinter struct is used as the default printer by Rustics. It serves as an example of a simple Printer implementation.
Units: Defines printable strings for a value’s units.

Enums§

StreamKind

Traits§

Histogram: The Histogram trait defines an interface for using a LogHistogram or FloatHistogram instance.
Printer: The Printer trait allows users to create custom output functions to match their I/O needs.
Rustics: The Rustics trait is the main interface for collecting and querying statistics.

Functions§

biased_exponent: Extracts the raw exponent from an IEEE f64 value.
compute_kurtosis: Computes the sample kurtosis estimator.
compute_skewness: Computes the sample skewness.
compute_statistics: Computes the second and fourth moments about the mean given the values in StatisticsData. This is used when merging multiple Rustics instances for upper-level HierMember instances.
compute_variance: Computes a variance estimator.
estimate_moment_3: Estimates moment 3 about the mean.
exponent_bias: Returns the IEEE f64 exponent bias.
is_zero
make_title: The make_title() function concatenates two strings, inserting the “=>” marker for set hierarchy specification. It is probably of interest only to implementors of new Rustics types. It does omit the “=>” if the title prefix is empty.
max_biased_exponent
max_exponent
max_f64: Computes the maximum of two f64 values, being careful about NaNs.
min_exponent
min_f64: Computes the minimum of two f64 values, being careful about NaNs.
parse_histo_opts: Returns the float histogram options in a PrintOption instance, if present, or creates a set of defaults if no histogram options were specified.
parse_print_opts: Extracts the options in a PrintOption instance, providing defaults for options not specified.
parse_printer: Extracts a printer from a PrintOption instance or provides a stdout_printer() if no printer was specified.
parse_title: Extracts the title in a PrintOption instance, if present, or creates a default title using the name parameter, if no title was specified.
parse_units: Returns the units in a PrintOption instance, if given, or returns the defaults if no units were specified.
recover: This routine converts the data in RecoverData into estimators of the sum of the squares and 4th power of each sample. This is used when merging Rustics instances for use in a Hier instance.
sign: Extracts the sign from an f64 value.
stdout_printer: Creates a PrinterBox instance that sends output to stdout. This is the default printer for all Rustics types.
timer_box_hz: Returns the frequency of a timer in a box.
to_mantissa: Extracts the mantissa from an f64.

Type Aliases§

FloatHistogramBox
HistoOption
LogHistogramBox
PrintOption
PrinterBox
PrinterOption
TimerBox
TitleOption
UnitsOption

Crate rusticsCopy item path