[tor-commits] [sbws/master] docs: update documentation about relays' prioritization

[juga@xxxxxxxxxxxxxx]

commit 40a94b4a672654b8413c227f9e81e7ec8c7eaf23
Author: juga0 <juga@xxxxxxxxxx>
Date:   Tue Jan 22 10:05:36 2019 +0000

    docs: update documentation about relays' prioritization
    
    By using the method docstring, we don't need to keep updated
    documentation about the same functionallity.
    Also, the documentation in the method is simpler.
    I found this explanation complex, long and confusing.
    This is the most complex part of the code.
---
 docs/source/specification.rst | 51 +++++--------------------------------------
 1 file changed, 5 insertions(+), 46 deletions(-)

diff --git a/docs/source/specification.rst b/docs/source/specification.rst
index f35f517..698842d 100644
--- a/docs/source/specification.rst
+++ b/docs/source/specification.rst
@@ -94,52 +94,11 @@ How it all works
 
 We now describe various core parts of sbws.
 
-Simple relay prioritization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This may be the most complex part of sbws.
-
-Sbws makes an effort to prioritize measurements of relays that don't have many
-recent results. For example: relays that just joined the Tor network or relays
-that haven't been online in the past few days. This goal is achieved using a
-min-priority queue and the concept of *freshness*.
-
-Freshness is defined as the amount of time between when the measurement was
-made and the time sbws will stop considering it valid. Thus, a measurement made
-more recently will have more time until it is no longer valid (higher
-freshness) and a measurement made a long time ago will have very little time
-until it is no longer valid (lower freshness).
-
-Over time, sbws will make many measurements for a given relay. The sum of these
-measurements' freshnesses is the relay's priority. As we are prioritizing like
-a min-priority queue, a higher sum of freshnesses means *worse* priority while
-a lower sum of freshnesses means *better* priority.
-
-  Example: AlphaRelay33 joined the network yesterday and sbws has measured it
-  once so far. BetaRelay87 has been in the network for years and has been
-  getting measured regularly approximately once a day. BetaRelay87 has five
-  measurements that are still valid, with freshnesses 10, 100, 500, 1000, and
-  1500. AlphaRelay33's one measurement has freshness 3000. Because the sum of
-  BetaRelay87's 5 measurements is greater than AlphaRelay33's one measurement,
-  AlphaRelay33 has *better* priority and will be measured next before
-  BetaRelay87.
-
-  Example: AlphaRelay33 is still a brand new relay with its one measurement
-  in the last day with freshness 3000. CharlieRelay9 has been in the network
-  for a long time, but had technical issues last week and hasn't been online in
-  many days. When CharlieRelay9's operator finally gets him back online, he
-  still has one valid measurement with freshness 10. Because AlphaRelay33's
-  measurement is fresher, CharlieRelay9 has *better* priority and will get
-  measured first.
-
-Sometimes measurements fail. Hopefully they fail because of transient issues,
-and with that hope in mind, it would be nice if a relay with a failed
-measurement didn't have to wait a long time to have another chance at a
-successful measurement. For this reason, when summing the freshnesses of
-results for a given relay, sbws will artificially *reduce* the freshness for
-measurements that were not successful. This makes the sum of freshnesses lower
-for that relay, and therefore the priority *better* so it can be measured again
-sooner.
+In which order are relays measured?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automethod:: sbws.lib.relayprioritizer.RelayPrioritizer.best_priority
+   :noindex:
 
 Simple result storage
 ~~~~~~~~~~~~~~~~~~~~~



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits