[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnunet-scheme] branch master updated: doc: Document 'start-get!', 'put!
From: |
gnunet |
Subject: |
[gnunet-scheme] branch master updated: doc: Document 'start-get!', 'put!' and friends. |
Date: |
Wed, 29 Dec 2021 20:16:21 +0100 |
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.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gnunet-scheme] branch master updated: doc: Document 'start-get!', 'put!' and friends.,
gnunet <=