commit 40a94b4a672654b8413c227f9e81e7ec8c7eaf23 Author: juga0 juga@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 --- 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 ~~~~~~~~~~~~~~~~~~~~~