[tor-commits] [sbws/master] docs: update documentation about relays' prioritization
juga at torproject.org
juga at torproject.org
Fri Feb 15 17:51:28 UTC 2019
Author: juga0 <juga at riseup.net>
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
@@ -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
- 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
+In which order are relays measured?
+.. automethod:: sbws.lib.relayprioritizer.RelayPrioritizer.best_priority
Simple result storage
More information about the tor-commits