ACE_Stats Class Reference

Provides simple statistical analysis. More...

#include <Stats.h>

Collaboration diagram for ACE_Stats:

[legend]List of all members.

Public Member Functions
	ACE_Stats (void)
	Default constructor.
int	sample (const ACE_INT32 value)
ACE_UINT32	samples (void) const
	Access the number of samples provided so far.
ACE_INT32	min_value (void) const
	Value of the minimum sample provided so far.
ACE_INT32	max_value (void) const
	Value of the maximum sample provided so far.
void	mean (ACE_Stats_Value &mean, const ACE_UINT32 scale_factor=1)
int	std_dev (ACE_Stats_Value &std_dev, const ACE_UINT32 scale_factor=1)
int	print_summary (const u_int precision, const ACE_UINT32 scale_factor=1, FILE *=stdout) const
void	reset (void)
	Initialize internal state.
void	dump (void) const
	Print summary statistics to stdout.
Static Public Member Functions
static void	quotient (const ACE_UINT64 dividend, const ACE_UINT32 divisor, ACE_Stats_Value &quotient)
	Utility division function, for ACE_UINT64 dividend.
static void	quotient (const ACE_Stats_Value &dividend, const ACE_UINT32 divisor, ACE_Stats_Value &quotient)
	Utility division function, for ACE_Stats_Value dividend.
static void	square_root (const ACE_UINT64 n, ACE_Stats_Value &square_root)
Protected Attributes
u_int	overflow_
ACE_UINT32	number_of_samples_
	Number of samples.
ACE_INT32	min_
	Minimum sample value.
ACE_INT32	max_
	Maximum sample value.
ACE_Unbounded_Queue< ACE_INT32 >	samples_
	The samples.

---

Detailed Description

Provides simple statistical analysis.

Simple statistical analysis package. Prominent features are:

1. It does not use any floating point arithmetic.
2. It handles positive and/or negative sample values. The sample value type is ACE_INT32.
3. It uses 64 bit unsigned, but not 64 bit signed, quantities internally.
4. It checks for overflow of internal state.
5. It has no static variables of other than built-in types.

Example usage:

 * ACE_Stats stats;
 * for (u_int i = 0; i < n; ++i)
 * {
 * const ACE_UINT32 sample = ...;
 * stats.sample (sample);
 * }
 * stats.print_summary (3);
 * 

Definition at line 129 of file Stats.h.

---

Constructor & Destructor Documentation

ACE_INLINE ACE_Stats::ACE_Stats

(

void

)

Default constructor.

Definition at line 69 of file Stats.inl.

References reset().

{
  reset ();
}

---

Member Function Documentation

ACE_INLINE void ACE_Stats::dump

(

void

)

const

Print summary statistics to stdout.

Definition at line 97 of file Stats.inl.

References print_summary().

{
#if defined (ACE_HAS_DUMP)
  print_summary (3u);
#endif /* ACE_HAS_DUMP */
}

ACE_INLINE ACE_INT32 ACE_Stats::max_value

(

void

)

const

Value of the maximum sample provided so far.

Definition at line 90 of file Stats.inl.

References max_.

{
  return max_;
}

void ACE_Stats::mean	(	ACE_Stats_Value &	mean,
		const ACE_UINT32	scale_factor = 1
	)

Access the mean of all samples provided so far. The fractional part is to the specified number of digits. E.g., 3 fractional digits specifies that the fractional part is in thousandths.

Definition at line 66 of file Stats.cpp.

References ACE_UINT64_LITERAL, ACE_Unbounded_Queue_Iterator< T >::advance(), ACE_Unbounded_Queue_Iterator< T >::done(), ACE_Stats_Value::fractional(), ACE_Unbounded_Queue_Iterator< T >::next(), number_of_samples_, quotient(), sample(), samples_, and ACE_Stats_Value::whole().

Referenced by ACE_High_Res_Timer::calibrate(), and std_dev().

{
  if (number_of_samples_ > 0)
    {
#if defined ACE_LACKS_LONGLONG_T
      // If ACE_LACKS_LONGLONG_T, then ACE_UINT64 is a user-defined class.
      // To prevent having to construct a static of that class, declare it
      // on the stack, and construct it, in each function that needs it.
      const ACE_U_LongLong ACE_STATS_INTERNAL_OFFSET (0, 8);
#else  /* ! ACE_LACKS_LONGLONG_T */
      const ACE_UINT64 ACE_STATS_INTERNAL_OFFSET =
        ACE_UINT64_LITERAL (0x100000000);
#endif /* ! ACE_LACKS_LONGLONG_T */

      ACE_UINT64 sum = ACE_STATS_INTERNAL_OFFSET;
      ACE_Unbounded_Queue_Iterator<ACE_INT32> i (samples_);
      while (! i.done ())
        {
          ACE_INT32 *sample;
          if (i.next (sample))
            {
              sum += *sample;
              i.advance ();
            }
        }

      // sum_ was initialized with ACE_STATS_INTERNAL_OFFSET, so
      // subtract that off here.
      quotient (sum - ACE_STATS_INTERNAL_OFFSET,
                number_of_samples_ * scale_factor,
                m);
    }
  else
    {
      m.whole (0);
      m.fractional (0);
    }
}

ACE_INLINE ACE_INT32 ACE_Stats::min_value

(

void

)

const

Value of the minimum sample provided so far.

Definition at line 83 of file Stats.inl.

References min_.

{
  return min_;
}

int ACE_Stats::print_summary	(	const u_int	precision,
		const ACE_UINT32	scale_factor = 1,
		FILE *	= stdout
	)			const

Print summary statistics. If scale_factor is not 1, then the results are divided by it, i.e., each of the samples is scaled down by it. If internal overflow is reached with the specified scale factor, it successively tries to reduce it. Returns -1 if there is overflow even with a 0 scale factor.

Definition at line 212 of file Stats.cpp.

References ACE_TEXT, ACE_OS::fprintf(), max_, min_, overflow_, quotient(), samples(), ACE_OS::sprintf(), std_dev(), and ACE_OS::strerror().

Referenced by dump().

{
  ACE_TCHAR mean_string [128];
  ACE_TCHAR std_dev_string [128];
  ACE_TCHAR min_string [128];
  ACE_TCHAR max_string [128];
  int success = 0;

  for (int tmp_precision = precision;
       ! overflow_  &&  ! success  &&  tmp_precision >= 0;
       --tmp_precision)
    {
      // Build a format string, in case the C library doesn't support %*u.
      ACE_TCHAR format[32];
      if (tmp_precision == 0)
        ACE_OS::sprintf (format, ACE_TEXT ("%%%d"), tmp_precision);
      else
        ACE_OS::sprintf (format, ACE_TEXT ("%%d.%%0%du"), tmp_precision);

      ACE_Stats_Value u (tmp_precision);
      ((ACE_Stats *) this)->mean (u, scale_factor);
      ACE_OS::sprintf (mean_string, format, u.whole (), u.fractional ());

      ACE_Stats_Value sd (tmp_precision);
      if (((ACE_Stats *) this)->std_dev (sd, scale_factor))
        {
          success = 0;
          continue;
        }
      else
        {
          success = 1;
        }
      ACE_OS::sprintf (std_dev_string, format, sd.whole (), sd.fractional ());

      ACE_Stats_Value minimum (tmp_precision), maximum (tmp_precision);
      if (min_ != 0)
        {
          const ACE_UINT64 m (min_);
          quotient (m, scale_factor, minimum);
        }
      if (max_ != 0)
        {
          const ACE_UINT64 m (max_);
          quotient (m, scale_factor, maximum);
        }
      ACE_OS::sprintf (min_string, format,
                       minimum.whole (), minimum.fractional ());
      ACE_OS::sprintf (max_string, format,
                       maximum.whole (), maximum.fractional ());
    }

  if (success == 1)
    {
      ACE_OS::fprintf (file, ACE_TEXT ("samples: %u (%s - %s); mean: ")
                       ACE_TEXT ("%s; std dev: %s\n"),
                       samples (), min_string, max_string,
                       mean_string, std_dev_string);
      return 0;
    }
  else
    {
#if !defined (ACE_HAS_WINCE)
      ACE_OS::fprintf (file,
                       ACE_TEXT ("ACE_Stats::print_summary: OVERFLOW: %s\n"),
                       ACE_OS::strerror (overflow_));
#else
      // WinCE doesn't have strerror ;(
      ACE_OS::fprintf (file,
                       ACE_TEXT ("ACE_Stats::print_summary: OVERFLOW\n"));
#endif /* ACE_HAS_WINCE */
      return -1;
    }
}

void ACE_Stats::quotient	(	const ACE_Stats_Value &	dividend,
		const ACE_UINT32	divisor,
		ACE_Stats_Value &	quotient
	)			[static]

Utility division function, for ACE_Stats_Value dividend.

Definition at line 321 of file Stats.cpp.

References ACE_Stats_Value::fractional(), quotient(), and ACE_Stats_Value::whole().

{
  // The whole part of the division comes from simple integer division.
  quotient.whole (divisor == 0  ?  0  :  dividend.whole () / divisor);

  if (quotient.precision () > 0  ||  divisor == 0)
    {
      const ACE_UINT32 field = quotient.fractional_field ();

      // Fractional = (dividend % divisor) * 10^precision / divisor.
      quotient.fractional (dividend.whole () % divisor * field / divisor  +
                           dividend.fractional () / divisor);
    }
  else
    {
      // No fractional portion is requested, so don't bother
      // calculating it.
      quotient.fractional (0);
    }
}

void ACE_Stats::quotient	(	const ACE_UINT64	dividend,
		const ACE_UINT32	divisor,
		ACE_Stats_Value &	quotient
	)			[static]

Utility division function, for ACE_UINT64 dividend.

Definition at line 290 of file Stats.cpp.

Referenced by mean(), print_summary(), quotient(), and std_dev().

{
  // The whole part of the division comes from simple integer division.
  quotient.whole (static_cast<ACE_UINT32> (divisor == 0
                                           ?  0  :  dividend / divisor));

  if (quotient.precision () > 0  ||  divisor == 0)
    {
      const ACE_UINT32 field = quotient.fractional_field ();

      // Fractional = (dividend % divisor) * 10^precision / divisor

      // It would be nice to add round-up term:
      // Fractional = (dividend % divisor) * 10^precision / divisor  +
      //                10^precision/2 / 10^precision
      //            = ((dividend % divisor) * 10^precision  +  divisor) /
      //                divisor
      quotient.fractional (static_cast<ACE_UINT32> (
                             dividend % divisor * field / divisor));
    }
  else
    {
      // No fractional portion is requested, so don't bother
      // calculating it.
      quotient.fractional (0);
    }
}

void ACE_Stats::reset

(

void

)

Initialize internal state.

Definition at line 202 of file Stats.cpp.

References max_, min_, number_of_samples_, overflow_, ACE_Unbounded_Queue< T >::reset(), and samples_.

Referenced by ACE_Stats().

{
  overflow_ = 0u;
  number_of_samples_ = 0u;
  min_ = 0x7FFFFFFF;
  max_ = -0x8000 * 0x10000;
  samples_.reset ();
}

int ACE_Stats::sample

(

const ACE_INT32

value

)

Provide a new sample. Returns 0 on success, -1 if it fails due to running out of memory, or to rolling over of the sample count.

Definition at line 36 of file Stats.cpp.

References ACE_Unbounded_Queue< T >::enqueue_tail(), max_, min_, number_of_samples_, overflow_, and samples_.

Referenced by ACE_High_Res_Timer::calibrate(), mean(), and std_dev().

{
  if (samples_.enqueue_tail (value) == 0)
    {
      ++number_of_samples_;
      if (number_of_samples_ == 0)
        {
          // That's a lot of samples :-)
          overflow_ = EFAULT;
          return -1;
        }

      if (value < min_)
        min_ = value;

      if (value > max_)
        max_ = value;

      return 0;
    }
  else
    {
      // Probably failed due to running out of memory when trying to
      // enqueue the new value.
      overflow_ = errno;
      return -1;
    }
}

ACE_INLINE ACE_UINT32 ACE_Stats::samples

(

void

)

const

Access the number of samples provided so far.

Definition at line 76 of file Stats.inl.

References number_of_samples_.

Referenced by print_summary().

{
  return number_of_samples_;
}

void ACE_Stats::square_root	(	const ACE_UINT64	n,
		ACE_Stats_Value &	square_root
	)			[static]

Sqrt function, which uses an oversimplified version of Newton's method. It's not fast, but it doesn't require floating point support.

Definition at line 345 of file Stats.cpp.

References ACE_OS::floor().

Referenced by std_dev().

{
  ACE_UINT32 floor = 0;
  ACE_UINT32 ceiling = 0xFFFFFFFFu;
  ACE_UINT32 mid = 0;
  u_int i;

  // The maximum number of iterations is log_2 (2^64) == 64.
  for (i = 0; i < 64; ++i)
    {
      mid = (ceiling - floor) / 2  +  floor;
      if (floor == mid)
        // Can't divide the interval any further.
        break;
      else
        {
          // Multiply carefully to avoid overflow.
          ACE_UINT64 mid_squared = mid; mid_squared *= mid;
          if (mid_squared == n)
            break;
          else if (mid_squared < n)
            floor = mid;
          else
            ceiling = mid;
        }
    }

  square_root.whole (mid);
  ACE_UINT64 mid_squared = mid; mid_squared *= mid;

  if (square_root.precision ()  &&  mid_squared < n)
    {
      // (mid * 10^precision + fractional)^2 ==
      //   n^2 * 10^(precision * 2)

      const ACE_UINT32 field = square_root.fractional_field ();

      floor = 0;
      ceiling = field;
      mid = 0;

      // Do the 64-bit arithmetic carefully to avoid overflow.
      ACE_UINT64 target = n;
      target *= field;
      target *= field;

      ACE_UINT64 difference = 0;

      for (i = 0; i < square_root.precision (); ++i)
        {
          mid = (ceiling - floor) / 2 + floor;

          ACE_UINT64 current = square_root.whole () * field  +  mid;
          current *= square_root.whole () * field  +  mid;

          if (floor == mid)
            {
              difference = target - current;
              break;
            }
          else if (current <= target)
            floor = mid;
          else
            ceiling = mid;
        }

      // Check to see if the fractional part should be one greater.
      ACE_UINT64 next = square_root.whole () * field  +  mid + 1;
      next *= square_root.whole () * field  +  mid + 1;

      square_root.fractional (next - target < difference  ?  mid + 1  :  mid);
    }
  else
    {
      // No fractional portion is requested, so don't bother
      // calculating it.
      square_root.fractional (0);
    }
}

int ACE_Stats::std_dev	(	ACE_Stats_Value &	std_dev,
		const ACE_UINT32	scale_factor = 1
	)

Access the standard deviation, whole and fractional parts. See description of {mean} method for argument descriptions.

Definition at line 107 of file Stats.cpp.

References ACE_Unbounded_Queue_Iterator< T >::advance(), ACE_Unbounded_Queue_Iterator< T >::done(), mean(), ACE_Unbounded_Queue_Iterator< T >::next(), number_of_samples_, overflow_, quotient(), sample(), samples_, and square_root().

Referenced by print_summary().

{
  if (number_of_samples_ <= 1)
    {
      std_dev.whole (0);
      std_dev.fractional (0);
    }
  else
    {
      const ACE_UINT32 field = std_dev.fractional_field ();

      // The sample standard deviation is:
      //
      // sqrt (sum (sample_i - mean)^2 / (number_of_samples_ - 1))

      ACE_UINT64 mean_scaled;
      // Calculate the mean, scaled, so that we don't lose its
      // precision.
      ACE_Stats_Value avg (std_dev.precision ());
      mean (avg, 1u);
      avg.scaled_value (mean_scaled);

      // Calculate the summation term, of squared differences from the
      // mean.
      ACE_UINT64 sum_of_squares = 0;
      ACE_Unbounded_Queue_Iterator<ACE_INT32> i (samples_);
      while (! i.done ())
        {
          ACE_INT32 *sample;
          if (i.next (sample))
            {
              const ACE_UINT64 original_sum_of_squares = sum_of_squares;

              // Scale up by field width so that we don't lose the
              // precision of the mean.  Carefully . . .
              const ACE_UINT64 product (*sample * field);

              ACE_UINT64 difference;
              // NOTE: please do not reformat this code!  It //
              // works with the Diab compiler the way it is! //
              if  (product >= mean_scaled)                   //
                {                                            //
                  difference = product - mean_scaled;        //
                }                                            //
              else                                           //
                {                                            //
                  difference = mean_scaled - product;        //
                }                                            //
              // NOTE: please do not reformat this code!  It //
              // works with the Diab compiler the way it is! //

              // Square using 64-bit arithmetic.
              sum_of_squares += difference * ACE_U64_TO_U32 (difference);
              i.advance ();

              if (sum_of_squares < original_sum_of_squares)
                {
                  overflow_ = ENOSPC;
                  return -1;
                }
            }
        }

      // Divide the summation by (number_of_samples_ - 1), to get the
      // variance.  In addition, scale the variance down to undo the
      // mean scaling above.  Otherwise, it can get too big.
      ACE_Stats_Value variance (std_dev.precision ());
      quotient (sum_of_squares,
                (number_of_samples_ - 1) * field * field,
                variance);

      // Take the square root of the variance to get the standard
      // deviation.  First, scale up . . .
      ACE_UINT64 scaled_variance;
      variance.scaled_value (scaled_variance);

      // And scale up, once more, because we'll be taking the square
      // root.
      scaled_variance *= field;
      ACE_Stats_Value unscaled_standard_deviation (std_dev.precision ());
      square_root (scaled_variance,
                   unscaled_standard_deviation);

      // Unscale.
      quotient (unscaled_standard_deviation,
                scale_factor * field,
                std_dev);
    }

  return 0;
}

---

Member Data Documentation

ACE_INT32 ACE_Stats::max_ [protected]

Maximum sample value.

Definition at line 208 of file Stats.h.

Referenced by max_value(), print_summary(), reset(), and sample().

ACE_INT32 ACE_Stats::min_ [protected]

Minimum sample value.

Definition at line 205 of file Stats.h.

Referenced by min_value(), print_summary(), reset(), and sample().

ACE_UINT32 ACE_Stats::number_of_samples_ [protected]

Number of samples.

Definition at line 202 of file Stats.h.

Referenced by mean(), reset(), sample(), samples(), and std_dev().

u_int ACE_Stats::overflow_ [protected]

Internal indication of whether there has been overflow. Contains the errno corresponding to the cause of overflow.

Definition at line 199 of file Stats.h.

Referenced by print_summary(), reset(), sample(), and std_dev().

ACE_Unbounded_Queue<ACE_INT32> ACE_Stats::samples_ [protected]

The samples.

Definition at line 211 of file Stats.h.

Referenced by mean(), reset(), sample(), and std_dev().

---

The documentation for this class was generated from the following files:

• Stats.h
• Stats.cpp
• Stats.inl

---