• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 */
74