ACE/ace/Stats.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Stats.h
   6  *
   7  *  @author David L. Levine
   8  */
   9 //==========================================================================
  10
  11
  12 #ifndef ACE_STATS_H
  13 #define ACE_STATS_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include /**/ "ace/ACE_export.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/Unbounded_Queue.h"
  24 #include "ace/Log_Category.h"
  25 #include "ace/Basic_Stats.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 /**
  30  * @class ACE_Stats_Value
  31  *
  32  * @brief Helper class for ACE_Stats.
  33  *
  34  * Container struct for 64-bit signed quantity and its
  35  * precision.  It would be nicer to use a fixed-point class, but
  36  * this is sufficient.  Users typically don't need to use this
  37  * class directly; see ACE_Stats below.
  38  */
  39 class ACE_Export ACE_Stats_Value
  40 {
  41 public:
  42   /**
  43    * Constructor, which requires precision in terms of number of
  44    * decimal digits.  The more variation in the data, and the greater
  45    * the data values, the smaller the precision must be to avoid
  46    * overflow in the standard deviation calculation.  3 might be a
  47    * good value, or maybe 4.  5 will probably be too large for
  48    * non-trivial data sets.
  49    */
  50   ACE_Stats_Value (const u_int precision);
  51
  52   /// Accessor for precision.
  53   u_int precision (void) const;
  54
  55   /// Set the whole_ field.
  56   void whole (const ACE_UINT32);
  57
  58   /// Accessor for the whole_ field.
  59   ACE_UINT32 whole (void) const;
  60
  61   /// Set the fractional_ field.
  62   void fractional (const ACE_UINT32);
  63
  64   /// Accessor for the fractional_ field.
  65   ACE_UINT32 fractional (void) const;
  66
  67   /// Calculates the maximum value of the fractional portion, given its
  68   /// precision.
  69   ACE_UINT32 fractional_field (void) const;
  70
  71   /**
  72    * Access the value as an _unsigned_ 64 bit quantity.  It scales the
  73    * value up by {precision} decimal digits, so that no precision will
  74    * be lost.  It assumes that {whole_} is >= 0.
  75    */
  76   void scaled_value (ACE_UINT64 &) const;
  77
  78   /// Print to stdout.
  79   void dump (void) const;
  80
  81 private:
  82
  83   ACE_Stats_Value (void) {}
  84
  85 private:
  86   /// The integer portion of the value.
  87   ACE_UINT32 whole_;
  88
  89   /// The fractional portion of the value.
  90   ACE_UINT32 fractional_;
  91
  92   /**
  93    * The number of decimal digits of precision represented by
  94    * {fractional_}.  Not declared const, so the only way to change it
  95    * is via the assignment operator.
  96    */
  97   u_int precision_;
  98
  99 };
 100
 101 /**
 102  * @class ACE_Stats
 103  *
 104  * @brief Provides simple statistical analysis.
 105  *
 106  * Simple statistical analysis package.  Prominent features are:
 107  * -# It does not use any floating point arithmetic.
 108  * -# It handles positive and/or negative sample values.  The
 109  *    sample value type is ACE_INT32.
 110  * -# It uses 64 bit unsigned, but not 64 bit signed, quantities
 111  *    internally.
 112  * -# It checks for overflow of internal state.
 113  * -# It has no static variables of other than built-in types.
 114  *
 115  * Example usage:
 116  *
 117  * @verbatim
 118  * ACE_Stats stats;
 119  * for (u_int i = 0; i < n; ++i)
 120  * {
 121  * const ACE_UINT32 sample = ...;
 122  * stats.sample (sample);
 123  * }
 124  * stats.print_summary (3);
 125  * @endverbatim
 126  */
 127 class ACE_Export ACE_Stats
 128 {
 129 public:
 130   /// Default constructor.
 131   ACE_Stats (void);
 132
 133   /// Provide a new sample.  Returns 0 on success, -1 if it fails due
 134   /// to running out of memory, or to rolling over of the sample count.
 135   int sample (const ACE_INT32 value);
 136
 137   /// Access the number of samples provided so far.
 138   ACE_UINT32 samples (void) const;
 139
 140   /// Value of the minimum sample provided so far.
 141   ACE_INT32 min_value (void) const;
 142
 143   /// Value of the maximum sample provided so far.
 144   ACE_INT32 max_value (void) const;
 145
 146   /**
 147    * Access the mean of all samples provided so far.  The fractional
 148    * part is to the specified number of digits.  E.g., 3 fractional
 149    * digits specifies that the fractional part is in thousandths.
 150    */
 151   void mean (ACE_Stats_Value &mean,
 152              const ACE_UINT32 scale_factor = 1);
 153
 154   /// Access the standard deviation, whole and fractional parts.  See
 155   /// description of {mean} method for argument descriptions.
 156   int std_dev (ACE_Stats_Value &std_dev,
 157                const ACE_UINT32 scale_factor = 1);
 158
 159   /**
 160    * Print summary statistics.  If scale_factor is not 1, then the
 161    * results are divided by it, i.e., each of the samples is scaled
 162    * down by it.  If internal overflow is reached with the specified
 163    * scale factor, it successively tries to reduce it.  Returns -1 if
 164    * there is overflow even with a 0 scale factor.
 165    */
 166   int print_summary (const u_int precision,
 167                      const ACE_UINT32 scale_factor = 1,
 168                      FILE *
 169 #ifdef ACE_LACKS_STDOUT
 170                      = 0
 171 #else
 172                      = stdout
 173 #endif
 174                      ) const;
 175
 176   /// Initialize internal state.
 177   void reset (void);
 178
 179   /// Utility division function, for ACE_UINT64 dividend.
 180   static void quotient (const ACE_UINT64 dividend,
 181                         const ACE_UINT32 divisor,
 182                         ACE_Stats_Value &quotient);
 183
 184   /// Utility division function, for ACE_Stats_Value dividend.
 185   static void quotient (const ACE_Stats_Value &dividend,
 186                         const ACE_UINT32 divisor,
 187                         ACE_Stats_Value &quotient);
 188
 189   /**
 190    * Sqrt function, which uses an oversimplified version of Newton's
 191    * method.  It's not fast, but it doesn't require floating point
 192    * support.
 193    */
 194   static void square_root (const ACE_UINT64 n,
 195                            ACE_Stats_Value &square_root);
 196
 197   /// Print summary statistics to stdout.
 198   void dump (void) const;
 199
 200 protected:
 201   /// Internal indication of whether there has been overflow.  Contains
 202   /// the errno corresponding to the cause of overflow.
 203   u_int overflow_;
 204
 205   /// Number of samples.
 206   ACE_UINT32 number_of_samples_;
 207
 208   /// Minimum sample value.
 209   ACE_INT32 min_;
 210
 211   /// Maximum sample value.
 212   ACE_INT32 max_;
 213
 214   /// The samples.
 215   ACE_Unbounded_Queue <ACE_INT32> samples_;
 216 };
 217
 218 ACE_END_VERSIONED_NAMESPACE_DECL
 219
 220 #if defined (__ACE_INLINE__)
 221 # include "ace/Stats.inl"
 222 #endif /* __ACE_INLINE__ */
 223
 224 #include /**/ "ace/post.h"
 225
 226 #endif /* ! ACE_STATS_H */