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