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 () const;
  54
  55   /// Set the whole_ field.
  56   void whole (const ACE_UINT32);
  57
  58   /// Accessor for the whole_ field.
  59   ACE_UINT32 whole () const;
  60
  61   /// Set the fractional_ field.
  62   void fractional (const ACE_UINT32);
  63
  64   /// Accessor for the fractional_ field.
  65   ACE_UINT32 fractional () const;
  66
  67   /// Calculates the maximum value of the fractional portion, given its
  68   /// precision.
  69   ACE_UINT32 fractional_field () 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 () const;
  80
  81 private:
  82   ACE_Stats_Value () = default;
  83
  84 private:
  85   /// The integer portion of the value.
  86   ACE_UINT32 whole_;
  87
  88   /// The fractional portion of the value.
  89   ACE_UINT32 fractional_;
  90
  91   /**
  92    * The number of decimal digits of precision represented by
  93    * {fractional_}.  Not declared const, so the only way to change it
  94    * is via the assignment operator.
  95    */
  96   u_int precision_;
  97 };
  98
  99 /**
 100  * @class ACE_Stats
 101  *
 102  * @brief Provides simple statistical analysis.
 103  *
 104  * Simple statistical analysis package.  Prominent features are:
 105  * -# It does not use any floating point arithmetic.
 106  * -# It handles positive and/or negative sample values.  The
 107  *    sample value type is ACE_INT32.
 108  * -# It uses 64 bit unsigned, but not 64 bit signed, quantities
 109  *    internally.
 110  * -# It checks for overflow of internal state.
 111  * -# It has no static variables of other than built-in types.
 112  *
 113  * Example usage:
 114  *
 115  * @verbatim
 116  * ACE_Stats stats;
 117  * for (u_int i = 0; i < n; ++i)
 118  * {
 119  * const ACE_UINT32 sample = ...;
 120  * stats.sample (sample);
 121  * }
 122  * stats.print_summary (3);
 123  * @endverbatim
 124  */
 125 class ACE_Export ACE_Stats
 126 {
 127 public:
 128   /// Default constructor.
 129   ACE_Stats ();
 130
 131   /// Provide a new sample.  Returns 0 on success, -1 if it fails due
 132   /// to running out of memory, or to rolling over of the sample count.
 133   int sample (const ACE_INT32 value);
 134
 135   /// Access the number of samples provided so far.
 136   ACE_UINT32 samples () const;
 137
 138   /// Value of the minimum sample provided so far.
 139   ACE_INT32 min_value () const;
 140
 141   /// Value of the maximum sample provided so far.
 142   ACE_INT32 max_value () const;
 143
 144   /**
 145    * Access the mean of all samples provided so far.  The fractional
 146    * part is to the specified number of digits.  E.g., 3 fractional
 147    * digits specifies that the fractional part is in thousandths.
 148    */
 149   void mean (ACE_Stats_Value &mean,
 150              const ACE_UINT32 scale_factor = 1);
 151
 152   /// Access the standard deviation, whole and fractional parts.  See
 153   /// description of {mean} method for argument descriptions.
 154   int std_dev (ACE_Stats_Value &std_dev,
 155                const ACE_UINT32 scale_factor = 1);
 156
 157   /**
 158    * Print summary statistics.  If scale_factor is not 1, then the
 159    * results are divided by it, i.e., each of the samples is scaled
 160    * down by it.  If internal overflow is reached with the specified
 161    * scale factor, it successively tries to reduce it.  Returns -1 if
 162    * there is overflow even with a 0 scale factor.
 163    */
 164   int print_summary (const u_int precision,
 165                      const ACE_UINT32 scale_factor = 1,
 166                      FILE *
 167 #ifdef ACE_LACKS_STDOUT
 168                      = 0
 169 #else
 170                      = stdout
 171 #endif
 172                      ) const;
 173
 174   /// Initialize internal state.
 175   void reset ();
 176
 177   /// Utility division function, for ACE_UINT64 dividend.
 178   static void quotient (const ACE_UINT64 dividend,
 179                         const ACE_UINT32 divisor,
 180                         ACE_Stats_Value &quotient);
 181
 182   /// Utility division function, for ACE_Stats_Value dividend.
 183   static void quotient (const ACE_Stats_Value &dividend,
 184                         const ACE_UINT32 divisor,
 185                         ACE_Stats_Value &quotient);
 186
 187   /**
 188    * Sqrt function, which uses an oversimplified version of Newton's
 189    * method.  It's not fast, but it doesn't require floating point
 190    * support.
 191    */
 192   static void square_root (const ACE_UINT64 n,
 193                            ACE_Stats_Value &square_root);
 194
 195   /// Print summary statistics to stdout.
 196   void dump () const;
 197
 198 protected:
 199   /// Internal indication of whether there has been overflow.  Contains
 200   /// the errno corresponding to the cause of overflow.
 201   u_int overflow_;
 202
 203   /// Number of samples.
 204   ACE_UINT32 number_of_samples_;
 205
 206   /// Minimum sample value.
 207   ACE_INT32 min_;
 208
 209   /// Maximum sample value.
 210   ACE_INT32 max_;
 211
 212   /// The samples.
 213   ACE_Unbounded_Queue <ACE_INT32> samples_;
 214 };
 215
 216 ACE_END_VERSIONED_NAMESPACE_DECL
 217
 218 #if defined (__ACE_INLINE__)
 219 # include "ace/Stats.inl"
 220 #endif /* __ACE_INLINE__ */
 221
 222 #include /**/ "ace/post.h"
 223
 224 #endif /* ! ACE_STATS_H */