Add time averaged stats for future alarm list work.

This is a trivial C89-ification of the []2 implementation of the same idea.
Indeed the implementation files and tests have been branched from the [] versions.
	Change on 2014/12/15 by ctiller <ctiller@google.com>
-------------
Created by MOE: http://code.google.com/p/moe-java
MOE_MIGRATED_REVID=82168822

build.json

@@ -127,6 +127,7 @@
         "src/core/iomgr/tcp_client_posix.c",
         "src/core/iomgr/tcp_posix.c",
         "src/core/iomgr/tcp_server_posix.c",
+        "src/core/iomgr/time_averaged_stats.c",
         "src/core/security/auth.c",
         "src/core/security/base64.c",
         "src/core/security/credentials.c",
@@ -222,6 +223,7 @@
         "src/core/iomgr/tcp_client.h",
         "src/core/iomgr/tcp_posix.h",
         "src/core/iomgr/tcp_server.h",
+        "src/core/iomgr/time_averaged_stats.h",
         "src/core/security/auth.h",
         "src/core/security/base64.h",
         "src/core/security/credentials.h",
@@ -581,6 +583,18 @@
         "gpr"
       ]
     },
+    {
+      "name": "time_averaged_stats_test",
+      "build": "test",
+      "src": [
+        "test/core/iomgr/time_averaged_stats_test.c"
+      ],
+      "deps": [
+        "grpc_test_util",
+        "grpc",
+        "gpr"
+      ]
+    },
     {
       "name": "chttp2_stream_encoder_test",
       "build": "test",

src/core/iomgr/time_averaged_stats.c

@@ -0,0 +1,77 @@
+/*
+ *
+ * Copyright 2014, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+#include "src/core/iomgr/time_averaged_stats.h"
+
+void grpc_time_averaged_stats_init(grpc_time_averaged_stats *stats,
+                                   double init_avg, double regress_weight,
+                                   double persistence_factor) {
+  stats->init_avg = init_avg;
+  stats->regress_weight = regress_weight;
+  stats->persistence_factor = persistence_factor;
+  stats->batch_total_value = 0;
+  stats->batch_num_samples = 0;
+  stats->aggregate_total_weight = 0;
+  stats->aggregate_weighted_avg = init_avg;
+}
+
+void grpc_time_averaged_stats_add_sample(grpc_time_averaged_stats *stats,
+                                         double value) {
+  stats->batch_total_value += value;
+  ++stats->batch_num_samples;
+}
+
+double grpc_time_averaged_stats_update_average(
+    grpc_time_averaged_stats *stats) {
+  /* Start with the current batch: */
+  double weighted_sum = stats->batch_total_value;
+  double total_weight = stats->batch_num_samples;
+  if (stats->regress_weight > 0) {
+    /* Add in the regression towards init_avg_: */
+    weighted_sum += stats->regress_weight * stats->init_avg;
+    total_weight += stats->regress_weight;
+  }
+  if (stats->persistence_factor > 0) {
+    /* Add in the persistence: */
+    const double prev_sample_weight =
+        stats->persistence_factor * stats->aggregate_total_weight;
+    weighted_sum += prev_sample_weight * stats->aggregate_weighted_avg;
+    total_weight += prev_sample_weight;
+  }
+  stats->aggregate_weighted_avg =
+      (total_weight > 0) ? (weighted_sum / total_weight) : stats->init_avg;
+  stats->aggregate_total_weight = total_weight;
+  stats->batch_num_samples = 0;
+  stats->batch_total_value = 0;
+  return stats->aggregate_weighted_avg;
+}

src/core/iomgr/time_averaged_stats.h

@@ -0,0 +1,88 @@
+/*
+ *
+ * Copyright 2014, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+#ifndef __GRPC_INTERNAL_IOMGR_TIME_AVERAGED_STATS_H_
+#define __GRPC_INTERNAL_IOMGR_TIME_AVERAGED_STATS_H_
+
+/* This tracks a time-decaying weighted average.  It works by collecting
+   batches of samples and then mixing their average into a time-decaying
+   weighted mean.  It is designed for batch operations where we do many adds
+   before updating the average. */
+
+typedef struct {
+  /* The initial average value.  This is the reported average until the first
+     grpc_time_averaged_stats_update_average call.  If a positive regress_weight
+     is used, we also regress towards this value on each update. */
+  double init_avg;
+  /* The sample weight of "init_avg" that is mixed in with each call to
+     grpc_time_averaged_stats_update_average.  If the calls to
+     grpc_time_averaged_stats_add_sample stop, this will cause the average to
+     regress back to the mean.  This should be non-negative.  Set it to 0 to
+     disable the bias.  A value of 1 has the effect of adding in 1 bonus sample
+     with value init_avg to each sample period. */
+  double regress_weight;
+  /* This determines the rate of decay of the time-averaging from one period
+     to the next by scaling the aggregate_total_weight of samples from prior
+     periods when combining with the latest period.  It should be in the range
+     [0,1].  A higher value adapts more slowly.  With a value of 0.5, if the
+     batches each have k samples, the samples_in_avg_ will grow to 2 k, so the
+     weighting of the time average will eventually be 1/3 new batch and 2/3
+     old average. */
+  double persistence_factor;
+
+  /* The total value of samples since the last UpdateAverage(). */
+  double batch_total_value;
+  /* The number of samples since the last UpdateAverage(). */
+  double batch_num_samples;
+  /* The time-decayed sum of batch_num_samples_ over previous batches.  This is
+     the "weight" of the old aggregate_weighted_avg_ when updating the
+     average. */
+  double aggregate_total_weight;
+  /* A time-decayed average of the (batch_total_value_ / batch_num_samples_),
+     computed by decaying the samples_in_avg_ weight in the weighted average. */
+  double aggregate_weighted_avg;
+} grpc_time_averaged_stats;
+
+/* See the comments on the members above for an explanation of init_avg,
+   regress_weight, and persistence_factor. */
+void grpc_time_averaged_stats_init(grpc_time_averaged_stats *stats,
+                                   double init_avg, double regress_weight,
+                                   double persistence_factor);
+/* Add a sample to the current batch. */
+void grpc_time_averaged_stats_add_sample(grpc_time_averaged_stats *stats,
+                                         double value);
+/* Complete a batch and compute the new estimate of the average sample
+   value. */
+double grpc_time_averaged_stats_update_average(grpc_time_averaged_stats *stats);
+
+#endif /* __GRPC_INTERNAL_IOMGR_TIME_AVERAGED_STATS_H_ */

test/core/iomgr/time_averaged_stats_test.c

@@ -0,0 +1,208 @@
+/*
+ *
+ * Copyright 2014, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
+#include "src/core/iomgr/time_averaged_stats.h"
+
+#include <math.h>
+
+#include <grpc/support/log.h>
+#include "test/core/util/test_config.h"
+
+#define EXPECT_EQ(a, b) GPR_ASSERT((a) == (b))
+#define EXPECT_DOUBLE_EQ(a, b) GPR_ASSERT(fabs((a) - (b)) < 1e-9)
+
+static void no_regress_no_persist_test_1() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0, 0.0);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(0, tas.aggregate_total_weight);
+
+  /* Should have no effect */
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(0, tas.aggregate_total_weight);
+
+  /* Should replace old average */
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(2000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1, tas.aggregate_total_weight);
+}
+
+static void no_regress_no_persist_test_2() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0, 0.0);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  /* Should replace init value */
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(2000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 3000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(3000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1, tas.aggregate_total_weight);
+}
+
+static void no_regress_no_persist_test_3() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0, 0.0);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  /* Should replace init value */
+  grpc_time_averaged_stats_add_sample(&tas, 2500);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(2500, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 3500);
+  grpc_time_averaged_stats_add_sample(&tas, 4500);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(4000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2, tas.aggregate_total_weight);
+}
+
+static void some_regress_no_persist_test() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0.5, 0.0);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(0, tas.aggregate_total_weight);
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  /* (2 * 2000 + 0.5 * 1000) / 2.5 */
+  EXPECT_DOUBLE_EQ(1800, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2.5, tas.aggregate_total_weight);
+}
+
+static void some_decay_test() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 1, 0.0);
+  EXPECT_EQ(1000, tas.aggregate_weighted_avg);
+  /* Should avg with init value */
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(1500, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(1500, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(1500, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2, tas.aggregate_total_weight);
+}
+
+static void no_regress_full_persist_test() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0, 1.0);
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(0, tas.aggregate_total_weight);
+
+  /* Should replace init value */
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_EQ(2000, tas.aggregate_weighted_avg);
+  EXPECT_EQ(1, tas.aggregate_total_weight);
+
+  /* Will result in average of the 3 samples. */
+  grpc_time_averaged_stats_add_sample(&tas, 2300);
+  grpc_time_averaged_stats_add_sample(&tas, 2300);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(2200, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(3, tas.aggregate_total_weight);
+}
+
+static void no_regress_some_persist_test() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0, 0.5);
+  /* Should replace init value */
+  grpc_time_averaged_stats_add_sample(&tas, 2000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(2000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 2500);
+  grpc_time_averaged_stats_add_sample(&tas, 4000);
+  grpc_time_averaged_stats_update_average(&tas);
+  EXPECT_DOUBLE_EQ(3000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2.5, tas.aggregate_total_weight);
+}
+
+static void some_regress_some_persist_test() {
+  grpc_time_averaged_stats tas;
+  grpc_time_averaged_stats_init(&tas, 1000, 0.4, 0.6);
+  /* Sample weight = 0 */
+  EXPECT_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_EQ(0, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_update_average(&tas);
+  /* (0.6 * 0 * 1000 + 0.4 * 1000 / 0.4) */
+  EXPECT_DOUBLE_EQ(1000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(0.4, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 2640);
+  grpc_time_averaged_stats_update_average(&tas);
+  /* (1 * 2640 + 0.6 * 0.4 * 1000 + 0.4 * 1000 / (1 + 0.6 * 0.4 + 0.4) */
+  EXPECT_DOUBLE_EQ(2000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(1.64, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 2876.8);
+  grpc_time_averaged_stats_update_average(&tas);
+  /* (1 * 2876.8 + 0.6 * 1.64 * 2000 + 0.4 * 1000 / (1 + 0.6 * 1.64 + 0.4) */
+  EXPECT_DOUBLE_EQ(2200, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2.384, tas.aggregate_total_weight);
+
+  grpc_time_averaged_stats_add_sample(&tas, 4944.32);
+  grpc_time_averaged_stats_update_average(&tas);
+  /* (1 * 4944.32 + 0.6 * 2.384 * 2200 + 0.4 * 1000) /
+         (1 + 0.6 * 2.384 + 0.4) */
+  EXPECT_DOUBLE_EQ(3000, tas.aggregate_weighted_avg);
+  EXPECT_DOUBLE_EQ(2.8304, tas.aggregate_total_weight);
+}
+
+int main(int argc, char **argv) {
+  grpc_test_init(argc, argv);
+  no_regress_no_persist_test_1();
+  no_regress_no_persist_test_2();
+  no_regress_no_persist_test_3();
+  some_regress_no_persist_test();
+  some_decay_test();
+  no_regress_full_persist_test();
+  no_regress_some_persist_test();
+  some_regress_some_persist_test();
+  return 0;
+}

vsprojects/vs2013/grpc.vcxproj

@@ -113,6 +113,7 @@
     <ClInclude Include="..\..\src\core\iomgr\tcp_client.h" />
     <ClInclude Include="..\..\src\core\iomgr\tcp_posix.h" />
     <ClInclude Include="..\..\src\core\iomgr\tcp_server.h" />
+    <ClInclude Include="..\..\src\core\iomgr\time_averaged_stats.h" />
     <ClInclude Include="..\..\src\core\security\auth.h" />
     <ClInclude Include="..\..\src\core\security\base64.h" />
     <ClInclude Include="..\..\src\core\security\credentials.h" />
@@ -226,6 +227,8 @@
     </ClCompile>
     <ClCompile Include="..\..\src\core\iomgr\tcp_server_posix.c">
     </ClCompile>
+    <ClCompile Include="..\..\src\core\iomgr\time_averaged_stats.c">
+    </ClCompile>
     <ClCompile Include="..\..\src\core\security\auth.c">
     </ClCompile>
     <ClCompile Include="..\..\src\core\security\base64.c">