Add explanation for options [mirrors].use_benchmark_stats and [mirrors].benchmark_oblivion

 SYNOPSIS: use_benchmark_stats=0 | 1
If use_benchmark_stats=1 statistics on mirrors is used to rate them
and therefore improve performance.
Each time connection from a particular mirror closes mirror->dld_time,
and mirror->dld_size get increased (in case of unsuccessful connection
only time gets increased), so avg speed for a mirror can be
calculated:

          mirror->avg_speed=mirror->dld_size/mirror->dld_time.       (1)

When new segment is going to be started segget goes through the list of
the mirrors distfile/segment has, and asks each mirror for self_rating:

          "ulong self_rating=mirror->mirror_on_the_wall();".

This way segget chooses a mirror with the best self_rating. To calculate
self_rating mirrors use the following formula:

               self_rating=dld_time/dld_size*honesty.                 (2)

So mirrors actually say how bad they are.
Even mirrors can have critical times, so to give mirrors another chance
honesty was added to the formula (2). honesty can get values in
interval (0,1]. Each time connection from a mirror opens or closes mirror
sets its honesty=1. If mirror was asked for self_evaluation with
mirror->mirror_on_the_wall(), but wasn't chosen its honesty decreases
somewhat (see [mirror].benchmark_oblivion option), so next time it will
lie little bit more about how bad it's.
Default:
use_benchmark_results=1
***Note: at the moment use_benchmark_results can NOT be set to 0

BENCHMARK_OBLIVION
benchmark_oblivion option allows to adjust how fast segget "forgets"
benchmarking statistics on mirrors performance.
Each time mirror->mirror_on_the_wall() called, mirror decreases its
honesty (to have more chances next time) using the following formula:

       honesty=honesty*100/(100+settings.benchmark_oblivion)         (3)

Therefore, setting benchmark_oblivion=100 will make mirror look twice
less bad next time mirror->mirror_on_the_wall() called.
Default:
benchmark_oblivion=5

3 files changed, 41 insertions, 9 deletions

diff --git a/segget/distfile.cpp b/segget/distfile.cpp
index 14cafcf..1db54e5 100644
--- a/segget/distfile.cpp
+++ b/segget/distfile.cpp
@@ -163,7 +163,7 @@ void Tdistfile::provide_segment(CURLM* cm, uint connection_num, uint seg_num){
 	for (url_num=0; url_num<url_count; url_num++){
 		Pcurr_mirror=find_mirror(strip_mirror_name(url_list[url_num]));
 		if (Pcurr_mirror->get_active_num()<settings.max_connections_num_per_mirror){
-			curr_mirror_self_rating=Pcurr_mirror->mirror_mirror_on_the_wall();
+			curr_mirror_self_rating=Pcurr_mirror->mirror_on_the_wall();
 			if (curr_mirror_self_rating<best_mirror_self_rating){
 				best_mirror_num=url_num;
 				best_mirror_self_rating=curr_mirror_self_rating;
diff --git a/segget/mirror.cpp b/segget/mirror.cpp
index cb391ff..5677fc6 100644
--- a/segget/mirror.cpp
+++ b/segget/mirror.cpp
@@ -23,11 +23,11 @@ class Tmirror{
 			honesty(1){};
 		void	start();
 		void	stop(ulong time, uint size);
-		double mirror_mirror_on_the_wall();
+		double mirror_on_the_wall();
 		uint get_active_num(){return active_num;};
 };
 
-double Tmirror::mirror_mirror_on_the_wall(){
+double Tmirror::mirror_on_the_wall(){
 	double criterion=honesty*1000000000*dld_time/dld_size;
 	honesty=honesty*100/(100+settings.benchmark_oblivion);
 	return criterion;
@@ -63,12 +63,11 @@ Tmirror* find_mirror(string mirror_url){
 		debug("       time:"+toString(mirror_iterator->second->dld_time));
 		debug("       size:"+toString(mirror_iterator->second->dld_size));
 		debug("    honesty:"+toString(mirror_iterator->second->honesty));
-		debug("  criterion:"+toString(mirror_iterator->second->mirror_mirror_on_the_wall()));
+		debug("  criterion:"+toString(mirror_iterator->second->mirror_on_the_wall()));
 		return mirror_iterator->second;
 	}
 }
 
-
 string strip_mirror_name(string path){
 	string mirror_name;
 	mirror_name=path.substr(0,path.find("/",(path.find("://",0)+3)));
diff --git a/segget/segget.conf b/segget/segget.conf
index a7c0619..72f0135 100644
--- a/segget/segget.conf
+++ b/segget/segget.conf
@@ -149,15 +149,48 @@ max_connections_num_per_mirror=1
 collect_benchmark_stats_on=1
 
 # SYNOPSIS: use_benchmark_stats=0 | 1
-# If use_benchmark_stats=1 statistics on mirrors is used to rate them and 
-# therefore improve performance.
+# If use_benchmark_stats=1 statistics on mirrors is used to rate them 
+# and therefore improve performance.
+# Each time connection from a particular mirror closes mirror->dld_time, 
+# and mirror->dld_size get increased (in case of unsuccessful connection
+# only time gets increased), so avg speed for a mirror can be
+# calculated:
+# 
+#           mirror->avg_speed=mirror->dld_size/mirror->dld_time.       (1)
+#
+# When new segment is going to be started segget goes through the list of
+# the mirrors distfile/segment has, and asks each mirror for self_rating:
+#
+#          "ulong self_rating=mirror->mirror_on_the_wall();". 
+#
+# This way segget chooses a mirror with the best self_rating. To calculate 
+# self_rating mirrors use the following formula:
+#
+#               self_rating=dld_time/dld_size*honesty.                 (2)
+#
+# So mirrors actually say how bad they are.
+# Even mirrors can have critical times, so to give mirrors another chance 
+# honesty was added to the formula (2). honesty can get values in 
+# interval (0,1]. Each time connection from a mirror opens or closes mirror
+# sets its honesty=1. If mirror was asked for self_evaluation with 
+# mirror->mirror_on_the_wall(), but wasn't chosen its honesty decreases
+# somewhat (see [mirror].benchmark_oblivion option), so next time it will 
+# lie little bit more about how bad it's.
 # Default:
-# use_benchmark_results=1 (Note: at the moment can NOT be changed)
+# use_benchmark_results=1
+# ***Note: at the moment use_benchmark_results can NOT be set to 0
 use_benchmark_stats=1
 
 # BENCHMARK_OBLIVION
 # benchmark_oblivion option allows to adjust how fast segget "forgets" 
-# benchmarking statistics on mirrors performance.
+# benchmarking statistics on mirrors performance. 
+# Each time mirror->mirror_on_the_wall() called, mirror decreases its
+# honesty (to have more chances next time) using the following formula:
+#
+#       honesty=honesty*100/(100+settings.benchmark_oblivion)         (3)
+#
+# Therefore, setting benchmark_oblivion=100 will make mirror look twice
+# less bad next time mirror->mirror_on_the_wall() called.
 # Default:
 # benchmark_oblivion=5
 benchmark_oblivion=5