dep/ACE_wrappers/ace/Stats.h

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