[gnunet-scheme] 187/324: doc: Document the ‘network size estimation’ API.

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a commit to branch master
in repository gnunet-scheme.

commit ac352798ac978e5ee242de66a043dfdcbe74ed06
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Thu Aug 19 21:29:27 2021 +0200

    doc: Document the ‘network size estimation’ API.
    
    * doc/scheme-gnunet.tm (Estimation of the size of the network):
      Unstub.
---
 doc/scheme-gnunet.tm | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 607c87c..7157d0b 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -258,8 +258,56 @@
 
   <section|Estimation of the size of the network>
 
-  GNUnet has a service that roughly estimates the size of the network \U
-  i.e., the number of peers
+  <index|network size estimation>GNUnet has a service that roughly estimates
+  the size of the network \U i.e., the number of peers.<space|1em>The module
+  <scm|(gnu gnunet nse client)> can be used to interact with this
+  service.<space|1em>The connection is made with the procedure <scm|connect>,
+  which is accepts a <with|font-shape|italic|configuration> (see
+  <todo|reference>) and some optional keyword arguments.<space|1em>This
+  procedure can be called as <scm|(connect config #:updated updated
+  #:connected connected)>.<space|1em>It returns a <with|font-shape|italic|NSE
+  server object>.
+
+  The connection is made asynchronuously; the thunk <var|updated> will be
+  called when the connection has actually been made.<space|1em>Whenever a new
+  estimate becomes available, the (optional) procedure <var|connected> is
+  called with the new 
<with|font-shape|italic|estimate>.<space|1em>Alternatively,
+  the procedure <scm|estimate> can be called on the server object to return
+  the latest available estimate.<space|1em>If the
+  <with|font-shape|italic|server object> doesn't have an estimate yet, that
+  procedure will return <scm|#false> instead of an estimate.
+
+  The estimate object has a number of accessors:
+
+  <\explain>
+    <scm|(estimate:logarithmic-number-peers <var|estimate>)>
+  </explain|The base-2 logarithm of the number of peers (estimated), as a
+  flonum>
+
+  <\explain>
+    <scm|(estimate:number-peers <var|estimate>)>
+  </explain|The number of peers (estimated), as a flonum.<space|1em>This is
+  not necessarily an (inexact) <scm|integer?>, as it is only an estimate.>
+
+  <\explain>
+    <scm|(estimate:timestamp estimate)>
+  </explain|A timestamp when the estimate was made <todo|something about
+  epoch?>>
+
+  <\explain>
+    <scm|(estimate:standard-deviation <var|estimate>)>
+  </explain|The estimated standard deviation on the base-2 logarithm of
+  peers, calculated over the last 64 rounds, with the <math|<frac|N|N-1>>
+  correction.>
+
+  Assuming the network size is stable and the errors on the logarithmic
+  estimate are normally distributed, the procedure
+  <scm|estimate:standard-deviation> can be used to put probablistic error
+  bounds on the number of peers on the network. <todo|example>
+
+  <todo|reconnecting, disconnecting, <text-dots>>
+
+  <todo|what if the server sends bogus data (e.g. negative)>
 
   <chapter|Implementation details>
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.