[gnunet-scheme] branch master updated: doc: Document 'start-get!', 'put!' and friends.

[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 7ccff30  doc: Document 'start-get!', 'put!' and friends.
7ccff30 is described below

commit 7ccff309650fc1e3491e813c7e050d5620ebc75b
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Wed Dec 29 19:13:48 2021 +0000

    doc: Document 'start-get!', 'put!' and friends.
    
    * doc/scheme-gnunet.tm (Accessing data in the DHT): Document
      'start-get!', 'put!', 'copy-datum' and 'copy-search-result'.
    * gnu/gnunet/dht/client.scm (start-get!, put!): Adjust docstrings.
---
 doc/scheme-gnunet.tm      | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 gnu/gnunet/dht/client.scm | 30 +++++++++++++++++++-----------
 2 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 4900b7f..bd7573f 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -1129,7 +1129,52 @@
 
   <subsection|Accessing data in the DHT>
 
-  <todo|todo!>
+  To insert a datum into the DHT, the procedure <scm|put!> is used. To find
+  data matching a query, the procedure <scm|start-get!> is used.
+
+  <\explain>
+    <scm|(start-get! <var|server> <var|query> <var|found>)>
+  <|explain>
+    Search for data matching <var|query> in the DHT. When a datum is found,
+    call the unary procedure <var|found> on the search result. It is possible
+    to find multiple data matching a query. In that case, <var|found> is
+    called multiple times. Searching happens asynchronuously; to stop the
+    search, a fresh <em|search object> for controlling the search is
+    returned.
+
+    The procedure <var|found> is run from the context of <var|server>. As
+    such, if <var|found> blocks, then all operations on <var|server> might
+    block. As such, it is recommended for <var|found> to do as little as
+    possible by itself and instead delegate any work to a separate fiber.
+
+    To avoid expensive copies, the implementation can choose to reuse
+    internal buffers for the slices passed to <var|found>, which could be
+    overwritten after the call to <var|found>. As such, it might be necessary
+    to make a copy of the search result, using <scm|copy-search-result>.
+  </explain>
+
+  <\explain>
+    <scm|(put! <var|server> <var|insertion> <var|#:confirmed>)>
+  <|explain>
+    Perform the insertion <var|insertion>. When the datum has been inserted,
+    the optional thunk <var|confirmed> is called. A <em|put object> is
+    returned which can be used to cancel the insertion.
+
+    <todo|TODO: actually call <var|confirmed>>
+  </explain>
+
+  <\explain>
+    <scm|(copy-datum <var|old>)>
+  </explain|Make a copy of the datum <var|old>, such that modifications to
+  the slices in <var|old> do not impact the new datum.>
+
+  <\explain>
+    <scm|(copy-search-result <var|old>)>
+  </explain|Make a copy of the search result <var|old>, such that
+  modification to the slices in <var|old> do not impact the new search
+  result.>
+
+  <todo|cancellation>
 
   <subsection|How to handle invalid data>
 
diff --git a/gnu/gnunet/dht/client.scm b/gnu/gnunet/dht/client.scm
index f898494..51ed937 100644
--- a/gnu/gnunet/dht/client.scm
+++ b/gnu/gnunet/dht/client.scm
@@ -327,14 +327,21 @@ slices in @var{old} do not impact the new search result."
             (value->index type))))
 
     (define* (start-get! server query found)
-      "Perform an asynchronous GET operation on the DHT, and return a handle
-to control the GET operation.  Search for a block described by the query
-@var{found}.  Call the unary procedure @var{found} on every search result.
-
-(TODO: why does the DHT service include the key and type?).
-
-(TODO: Document: These slices must not be used after @var{found} returns,
-as the underlying buffer might be reused.)"
+      "Search for data matching query in the DHT. When a datum is found, call
+the unary procedure @var{found} on the search result. It is possible to find
+multiple data matching a query. In that case, found is called multiple times.
+Searching happens asynchronuously; to stop the search, a fresh search object
+for controlling the search is returned.
+
+The procedure found is run from the context of server. As such, if @var{found}
+blocks, then all operations on server might block. As such, it is recommended
+for found to do as little as possible by itself and instead delegate any work
+to a separate fiber.
+
+To avoid expensive copies, the implementation can choose to reuse internal
+buffers for the slices passed to @var{found}, which could be overwritten after
+the call to @var{found}. As such, it might be necessary to make a copy of the
+search result, using @lisp{copy-search-result}."
       ;; TODO: options, xquery ...
       (define id (fresh-id server))
       (define handle (%make-get server found query id 0)) ; TODO: options
@@ -345,10 +352,11 @@ as the underlying buffer might be reused.)"
       handle)
 
     (define* (put! server insertion #:key (confirmed values))
-      "Perform an asynchronous PUT operation on the DHT, inserting
-the information described by @var{insertion} into the DHT.
+      "Perform the insertion @var{insertion}. When the datum has been inserted,
+the thunk @var{confirmed} is called. A @emph{put object} is returned which can
+be used to stop the insertion.
 
-TODO @var{confirmed} ..."
+TODO actually call @var{confirmed}"
       ;; Prepare the message to send.
       (define datum (insertion->datum insertion))
       (define put-message

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