legacy-libs/grpc-cloned/deps/grpc/src/core/lib/iomgr/time_averaged_stats.h

   1 /*
   2  *
   3  * Copyright 2015 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_LIB_IOMGR_TIME_AVERAGED_STATS_H
  20 #define GRPC_CORE_LIB_IOMGR_TIME_AVERAGED_STATS_H
  21
  22 /* This tracks a time-decaying weighted average.  It works by collecting
  23    batches of samples and then mixing their average into a time-decaying
  24    weighted mean.  It is designed for batch operations where we do many adds
  25    before updating the average. */
  26
  27 typedef struct {
  28   /* The initial average value.  This is the reported average until the first
  29      grpc_time_averaged_stats_update_average call.  If a positive regress_weight
  30      is used, we also regress towards this value on each update. */
  31   double init_avg;
  32   /* The sample weight of "init_avg" that is mixed in with each call to
  33      grpc_time_averaged_stats_update_average.  If the calls to
  34      grpc_time_averaged_stats_add_sample stop, this will cause the average to
  35      regress back to the mean.  This should be non-negative.  Set it to 0 to
  36      disable the bias.  A value of 1 has the effect of adding in 1 bonus sample
  37      with value init_avg to each sample period. */
  38   double regress_weight;
  39   /* This determines the rate of decay of the time-averaging from one period
  40      to the next by scaling the aggregate_total_weight of samples from prior
  41      periods when combining with the latest period.  It should be in the range
  42      [0,1].  A higher value adapts more slowly.  With a value of 0.5, if the
  43      batches each have k samples, the samples_in_avg_ will grow to 2 k, so the
  44      weighting of the time average will eventually be 1/3 new batch and 2/3
  45      old average. */
  46   double persistence_factor;
  47
  48   /* The total value of samples since the last UpdateAverage(). */
  49   double batch_total_value;
  50   /* The number of samples since the last UpdateAverage(). */
  51   double batch_num_samples;
  52   /* The time-decayed sum of batch_num_samples_ over previous batches.  This is
  53      the "weight" of the old aggregate_weighted_avg_ when updating the
  54      average. */
  55   double aggregate_total_weight;
  56   /* A time-decayed average of the (batch_total_value_ / batch_num_samples_),
  57      computed by decaying the samples_in_avg_ weight in the weighted average. */
  58   double aggregate_weighted_avg;
  59 } grpc_time_averaged_stats;
  60
  61 /* See the comments on the members above for an explanation of init_avg,
  62    regress_weight, and persistence_factor. */
  63 void grpc_time_averaged_stats_init(grpc_time_averaged_stats* stats,
  64                                    double init_avg, double regress_weight,
  65                                    double persistence_factor);
  66 /* Add a sample to the current batch. */
  67 void grpc_time_averaged_stats_add_sample(grpc_time_averaged_stats* stats,
  68                                          double value);
  69 /* Complete a batch and compute the new estimate of the average sample
  70    value. */
  71 double grpc_time_averaged_stats_update_average(grpc_time_averaged_stats* stats);
  72
  73 #endif /* GRPC_CORE_LIB_IOMGR_TIME_AVERAGED_STATS_H */