[gnunet-scheme] branch master updated: doc: Have some ideas for data structures for accessing the DHT.

[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.

The following commit(s) were added to refs/heads/master by this push:
     new 0a8098e  doc: Have some ideas for data structures for accessing the 
DHT.
0a8098e is described below

commit 0a8098e3db39b5029dc9714b0ecf59fe72324b87
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Sat Dec 25 22:54:53 2021 +0000

    doc: Have some ideas for data structures for accessing the DHT.
    
    Currently unimplemented!
    
    * doc/scheme-gnunet.tm (Accessing the DHT): New section.
---
 doc/scheme-gnunet.tm | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index f388f79..b6316cc 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -1049,6 +1049,97 @@
   <scm|estimate:standard-deviation> can be used to put probablistic error
   bounds on the number of peers on the network. <todo|example>
 
+  <section|Accessing the DHT>
+
+  GNUnet has a service that maintains a <em|distributed hash table>, mapping
+  keys to values. The module <scm|(gnu gnunet dht client)> can be used to
+  interact with the service. The connection can be made with the procedure
+  <scm|connect> <todo|document parameters>. It returns a <em|DHT server
+  object>. <todo|disconnection / reconnection>
+
+  <\warning>
+    The code currently implements a different API. To be corrected soon!
+  </warning>
+
+  <subsection|Data in the DHT>
+
+  To insert data into the DHT, the DHT service needs various information \U
+  the key and the value, but also some other information. Likewise, when the
+  DHT service has found the datum, this information is available as well. A
+  datum in the DHT is represented as a <em|datum object>. The object holding
+  the information required for inserting something in the DHT is called an
+  <em|insertion object>. Likewise, the information of searching for something
+  in the DHT is in a <em|query object>. The result of a query is a <em|search
+  result object>.
+
+  These objects only hold information; creating them does not have any side
+  effects.
+
+  <\explain>
+    <scm|(make-datum <var|type> <var|key> <var|value> <var|#:expiration>)>
+  <|explain>
+    Make a datum object of block type <var|type> (or its corresponding
+    numeric value), with key <var|key> (a readable <scm|/hashcode:512>
+    bytevector slice), value <var|value> (a readable bytevector slice)
+    expiring at <var|expiration> (<todo|type, epoch>). The keyword argument
+    <var|expiration> is optional, see <reference|???>.
+
+    The type can be retrieved with the accessor <scm|datum-type>, returning
+    the numeric value of the block type. The accessors <scm|datum-key>,
+    <scm|datum-value> and <scm|datum-expiration> return the key, value and
+    expiration time respectively. It can be tested if an object is a datum
+    object with the predicate <scm|datum?>.
+  </explain>
+
+  <\explain>
+    <scm|(datum-\<gtr\>insertion <var|datum> #:desired-replication-level)>
+  <|explain>
+    Make an insertion object for inserting the datum <var|datum>, desiring a
+    certain replication level <var|desired-replication-level>. This keyword
+    argument is optional, see <reference|???>. <todo|various options>.
+
+    The datum and desired replication level can be recovered with the
+    accessors <scm|insertion-\<gtr\>datum> and
+    <var|desired-replication-level>. It can be tested if an object is a datum
+    object with the predicate <scm|insertion?>.
+  </explain>
+
+  <\explain>
+    <scm|(make-query <var|type> <var|key> #:desired-replication-level)>
+  <|explain>
+    Make a query object for searching for a value of block type <var|type>
+    (or its corresponding numeric value), with key <var|key> (a readable
+    <scm|/hashcode:512> bytevector slice), at desired replication level
+    <scm|desired-replication-level>. This keyword argument is optional, see
+    <reference|???>. <todo|various options, xquery>
+
+    The type (as a numeric value), the key and the desired replication level
+    can be recovered with the accessors <scm|query-type>, <scm|query-key> and
+    <scm|query-desired-replication-level>. It can be tested if an object is a
+    query object with the predicate <scm|query?>.
+  </explain>
+
+  <\explain>
+    <scm|(datum-\<gtr\>search-result <var|datum> #:get-path #:put-path)>
+  </explain|Make a search result object for the datum <var|datum>. The datum
+  can be recovered with the accessor <scm|search-result-\<gtr\>datum>. It can
+  be tested if an object is a search result with the predicate
+  <scm|search-result?>. The optional keyword arguments <scm|get-path> and
+  <scm|put-path> are currently undocumented and untested.>
+
+  <subsection|Accessing data in the DHT>
+
+  <todo|todo!>
+
+  <subsection|How to handle invalid data>
+
+  <todo|todo!>
+
+  <subsection|Monitoring: spying on what other applications and peers are
+  doing>
+
+  <todo|todo!>
+
   <section|Cryptography>
 
   The module <scm|(gnu gnunet crypto)> has a few small wrappers around

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