Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Stats.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    Stats.h
00006  *
00007  *  $Id: Stats.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author David L. Levine
00010  */
00011 //==========================================================================
00012 
00013 
00014 #ifndef ACE_STATS_H
00015 #define ACE_STATS_H
00016 
00017 #include "ace/pre.h"
00018 
00019 #include "ace/ACE_export.h"
00020 
00021 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00022 # pragma once
00023 #endif /* ACE_LACKS_PRAGMA_ONCE */
00024 
00025 #include "ace/Unbounded_Queue.h"
00026 #include "ace/Log_Msg.h"
00027 #include "ace/Basic_Stats.h"
00028 #include "ace/OS.h"
00029 
00030 /**
00031  * @class ACE_Stats_Value
00032  *
00033  * @brief Helper class for ACE_Stats.
00034  *
00035  * Container struct for 64-bit signed quantity and its
00036  * precision.  It would be nicer to use a fixed-point class, but
00037  * this is sufficient.  Users typically don't need to use this
00038  * class directly; see ACE_Stats below.
00039  */
00040 class ACE_Export ACE_Stats_Value
00041 {
00042 public:
00043   /**
00044    * Constructor, which requires precision in terms of number of
00045    * decimal digits.  The more variation in the data, and the greater
00046    * the data values, the smaller the precision must be to avoid
00047    * overflow in the standard deviation calculation.  3 might be a
00048    * good value, or maybe 4.  5 will probably be too large for
00049    * non-trivial data sets.
00050    */
00051   ACE_Stats_Value (const u_int precision);
00052 
00053   /// Accessor for precision.
00054   u_int precision (void) const;
00055 
00056   /// Set the whole_ field.
00057   void whole (const ACE_UINT32);
00058 
00059   /// Accessor for the whole_ field.
00060   ACE_UINT32 whole (void) const;
00061 
00062   /// Set the fractional_ field.
00063   void fractional (const ACE_UINT32);
00064 
00065   /// Accessor for the fractional_ field.
00066   ACE_UINT32 fractional (void) const;
00067 
00068   /// Calculates the maximum value of the fractional portion, given its
00069   /// precision.
00070   ACE_UINT32 fractional_field (void) const;
00071 
00072   /**
00073    * Access the value as an _unsigned_ 64 bit quantity.  It scales the
00074    * value up by <precision> decimal digits, so that no precision will
00075    * be lost.  It assumes that <whole_> is >= 0.
00076    */
00077   void scaled_value (ACE_UINT64 &) const;
00078 
00079   /// Print to stdout.
00080   void dump (void) const;
00081 
00082 private:
00083   /// The integer portion of the value.
00084   ACE_UINT32 whole_;
00085 
00086   /// The fractional portion of the value.
00087   ACE_UINT32 fractional_;
00088 
00089   /**
00090    * The number of decimal digits of precision represented by
00091    * <fractional_>.  Not declared const, so the only way to change it
00092    * is via the assignment operator.
00093    */
00094   u_int precision_;
00095 
00096   ACE_UNIMPLEMENTED_FUNC (ACE_Stats_Value (void))
00097 };
00098 
00099 /**
00100  * @class ACE_Stats
00101  *
00102  * @brief Provides simple statistical analysis.
00103  *
00104  * Simple statistical analysis package.  Prominent features are:
00105  * -# It does not use any floating point arithmetic.
00106  * -# It handles positive and/or negative sample values.  The
00107  *    sample value type is ACE_INT32.
00108  * -# It uses 64 bit unsigned, but not 64 bit signed, quantities
00109  *    internally.
00110  * -# It checks for overflow of internal state.
00111  * -# It has no static variables of other than built-in types.
00112  *
00113  * Example usage:
00114  *
00115  * @verbatim
00116  * ACE_Stats stats;
00117  * for (u_int i = 0; i < n; ++i)
00118  * {
00119  * const ACE_UINT32 sample = ...;
00120  * stats.sample (sample);
00121  * }
00122  * stats.print_summary (3);
00123  * @endverbatim
00124  */
00125 class ACE_Export ACE_Stats
00126 {
00127 public:
00128   /// Default constructor.
00129   ACE_Stats (void);
00130 
00131   /// Provide a new sample.  Returns 0 on success, -1 if it fails due
00132   /// to running out of memory, or to rolling over of the sample count.
00133   int sample (const ACE_INT32 value);
00134 
00135   /// Access the number of samples provided so far.
00136   ACE_UINT32 samples (void) const;
00137 
00138   /// Value of the minimum sample provided so far.
00139   ACE_INT32 min_value (void) const;
00140 
00141   /// Value of the maximum sample provided so far.
00142   ACE_INT32 max_value (void) const;
00143 
00144   /**
00145    * Access the mean of all samples provided so far.  The fractional
00146    * part is to the specified number of digits.  E.g., 3 fractional
00147    * digits specifies that the fractional part is in thousandths.
00148    */
00149   void mean (ACE_Stats_Value &mean,
00150              const ACE_UINT32 scale_factor = 1);
00151 
00152   /// Access the standard deviation, whole and fractional parts.  See
00153   /// description of <mean> method for argument descriptions.
00154   int std_dev (ACE_Stats_Value &std_dev,
00155                const ACE_UINT32 scale_factor = 1);
00156 
00157   /**
00158    * Print summary statistics.  If scale_factor is not 1, then the
00159    * results are divided by it, i.e., each of the samples is scaled
00160    * down by it.  If internal overflow is reached with the specified
00161    * scale factor, it successively tries to reduce it.  Returns -1 if
00162    * there is overflow even with a 0 scale factor.
00163    */
00164   int print_summary (const u_int precision,
00165                      const ACE_UINT32 scale_factor = 1,
00166                      FILE * = stdout) const;
00167 
00168   /// Initialize internal state.
00169   void reset (void);
00170 
00171   /// Utility division function, for ACE_UINT64 dividend.
00172   static void quotient (const ACE_UINT64 dividend,
00173                         const ACE_UINT32 divisor,
00174                         ACE_Stats_Value &quotient);
00175 
00176   /// Utility division function, for ACE_Stats_Value dividend.
00177   static void quotient (const ACE_Stats_Value &dividend,
00178                         const ACE_UINT32 divisor,
00179                         ACE_Stats_Value &quotient);
00180 
00181   /**
00182    * Sqrt function, which uses an oversimplified version of Newton's
00183    * method.  It's not fast, but it doesn't require floating point
00184    * support.
00185    */
00186   static void square_root (const ACE_UINT64 n,
00187                            ACE_Stats_Value &square_root);
00188 
00189   /// Print summary statistics to stdout.
00190   void dump (void) const;
00191 
00192 private:
00193   /// Internal indication of whether there has been overflow.  Contains
00194   /// the errno corresponding to the cause of overflow.
00195   u_int overflow_;
00196 
00197   /// Number of samples.
00198   ACE_UINT32 number_of_samples_;
00199 
00200   /// Minimum sample value.
00201   ACE_INT32 min_;
00202 
00203   /// Maximum sample value.
00204   ACE_INT32 max_;
00205 
00206   /// The samples.
00207   ACE_Unbounded_Queue <ACE_INT32> samples_;
00208 };
00209 
00210 // ****************************************************************
00211 
00212 
00213 /// A simple class to make throughput and latency analysis.
00214 /**
00215  *
00216  * Keep the relevant information to perform throughput and latency
00217  * analysis, including:
00218  * -# Minimum, Average and Maximum latency
00219  * -# Jitter for the latency
00220  * -# Linear regression for throughput
00221  * -# Accumulate results from several samples to obtain aggregated
00222  *    results, across several threads or experiments.
00223  *
00224  * @todo The idea behind this class was to use linear regression to
00225  *       determine if the throughput was linear or exhibited jitter.
00226  *       Unfortunately it never worked quite right, so only average
00227  *       throughput is computed.
00228  */
00229 class ACE_Export ACE_Throughput_Stats : public ACE_Basic_Stats
00230 {
00231 public:
00232   /// Constructor
00233   ACE_Throughput_Stats (void);
00234 
00235   /// Store one sample
00236   void sample (ACE_UINT64 throughput, ACE_UINT64 latency);
00237 
00238   /// Update the values to reflect the stats in @a throughput
00239   void accumulate (const ACE_Throughput_Stats &throughput);
00240 
00241   /// Print down the stats
00242   void dump_results (const ACE_TCHAR* msg, ACE_UINT32 scale_factor);
00243 
00244   /// Dump the average throughput stats.
00245   static void dump_throughput (const ACE_TCHAR *msg,
00246                                ACE_UINT32 scale_factor,
00247                                ACE_UINT64 elapsed_time,
00248                                ACE_UINT32 samples_count);
00249 private:
00250   /// The last throughput measurement.
00251   ACE_UINT64 throughput_last_;
00252 
00253 #if 0
00254   /// These are the fields that we should keep to perform linear
00255   /// regression
00256   //@{
00257   ///@}
00258   ACE_UINT64 throughput_sum_x_;
00259   ACE_UINT64 throughput_sum_x2_;
00260   ACE_UINT64 throughput_sum_y_;
00261   ACE_UINT64 throughput_sum_y2_;
00262   ACE_UINT64 throughput_sum_xy_;
00263 #endif /* 0 */
00264 };
00265 
00266 
00267 #if defined (__ACE_INLINE__)
00268 # include "ace/Stats.i"
00269 #endif /* __ACE_INLINE__ */
00270 
00271 #include "ace/post.h"
00272 
00273 #endif /* ! ACE_STATS_H */

Generated on Mon Jun 16 11:21:24 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002