[gnunet-scheme] branch master updated (e037695 -> adc3a87)

[gnunet]

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

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

    from e037695  dht/client: Cancel unreachable non-lingering search 
operations.
     new 4022ab9  tests/distributed-hash-table: Prepare for not lingering by 
default.
     new bdd31c3  dht/client: By default don't linger.
     new ed0ed4a  NEWS: Document cancellability of DHT searches.
     new ef36bcb  NEWS: Let Emacs detect it is Org.
     new adc3a87  doc: Split ‘Concurrency’ chapter to separate file.

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 NEWS                             |  6 +++++-
 doc/concurrency.tm               | 28 ++++++++++++++++++++++++++++
 doc/distributed-hash-table.tm    |  8 ++++----
 doc/scheme-gnunet.tm             | 14 +-------------
 gnu/gnunet/dht/client.scm        |  9 ++++-----
 tests/distributed-hash-table.scm | 20 ++++++++++++++++----
 6 files changed, 58 insertions(+), 27 deletions(-)
 create mode 100644 doc/concurrency.tm

diff --git a/NEWS b/NEWS
index 2425898..c166771 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,4 @@
+# -*- mode: org; coding: utf-8 -*-
 # Copyright (C) 2021,2022 GNUnet e.V.
 # SPDX-License-Identifier: FSFAP
 # Copying and distribution of this file, with or without modification,
@@ -5,8 +6,11 @@
 # notice and this notice are preserved.  This file is offered as-is,
 # without any warranty.
 
--*- mode: org; coding: utf-8 -*-
 * Changes since 0.2
+** API
+   - DHT searches can now be stopped (‘cancelled’) with 'stop-get!'.
+     Additionally, DHT searches are automatically cancelled when the
+     search object becomes unreachable.
 ** Documentation
    - The ‘message-symbol’ network structure property is now defined for DHT
      messages and documented in the manual.  The aim is to make the code
diff --git a/doc/concurrency.tm b/doc/concurrency.tm
new file mode 100644
index 0000000..0166464
--- /dev/null
+++ b/doc/concurrency.tm
@@ -0,0 +1,28 @@
+<TeXmacs|2.1>
+
+<project|scheme-gnunet.tm>
+
+<style|tmmanual>
+
+<\body>
+  Scheme-GNUnet uses <code*|guile-fibers> for concurrency, but supports
+  POSIX-style threading as well, using the <code*|(ice-9 threads)> Guile
+  module. More concretely, this means <code*|spawn-fiber> is used by default
+  for starting asynchronuous computations and public procedures accept an
+  optional <scm|#:spawn> argument accepting a procedure like
+  <code*|spawn-fiber> or <code*|call-with-new-thread>.
+  \<#2018\>Conditions\<#2019\> can be used for synchronising concurrent
+  computations, see the documentation of <code*|guile-fibers> for details.
+
+  <paragraph|Repeated conditions>Scheme-GNUnet has a variant of fibers
+  conditions, named \<#2018\>repeated conditions\<#2019\>, in the module
+  <scm|(gnu gnunet concurrency repeated-condition)>.<space|1em>It is
+  unfortunately ill-documented.
+</body>
+
+<\initial>
+  <\collection>
+    <associate|page-medium|paper>
+    <associate|save-aux|false>
+  </collection>
+</initial>
\ No newline at end of file
diff --git a/doc/distributed-hash-table.tm b/doc/distributed-hash-table.tm
index b5b41f0..295a255 100644
--- a/doc/distributed-hash-table.tm
+++ b/doc/distributed-hash-table.tm
@@ -137,7 +137,7 @@
 
   <\explain>
     <scm|(start-get! <var|server> <var|query> <var|found>
-    <var|#:linger?>=#true)><index|start-get!>
+    <var|#:linger?>=#false)><index|start-get!>
   <|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
@@ -156,9 +156,9 @@
     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>.
 
-    When the boolean <var|linger?> is false, the search is automatically
-    cancelled when the search object becomes unreachable according to the GC.
-    <todo|actually implement this>
+    When the boolean <var|linger?> is false (this is the default), the search
+    is automatically cancelled when the search object becomes unreachable
+    according to the GC.
 
     <\warning>
       Guile currently (3.0.8) uses a conservative GC, so it cannot always
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 2f22bb3..046a965 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -214,19 +214,7 @@
 
   <chapter|Concurrency>
 
-  Scheme-GNUnet uses <code*|guile-fibers> for concurrency, but supports
-  POSIX-style threading as well, using the <code*|(ice-9 threads)> Guile
-  module. More concretely, this means <code*|spawn-fiber> is used by default
-  for starting asynchronuous computations and public procedures accept an
-  optional <scm|#:spawn> argument accepting a procedure like
-  <code*|spawn-fiber> or <code*|call-with-new-thread>.
-  \<#2018\>Conditions\<#2019\> can be used for synchronising concurrent
-  computations, see the documentation of <code*|guile-fibers> for details.
-
-  <paragraph|Repeated conditions>Scheme-GNUnet has a variant of fibers
-  conditions, named \<#2018\>repeated conditions\<#2019\>, in the module
-  <scm|(gnu gnunet concurrency repeated-condition)>.<space|1em>It is
-  unfortunately ill-documented.
+  <include|concurrency.tm>
 
   <chapter|Configuration>
 
diff --git a/gnu/gnunet/dht/client.scm b/gnu/gnunet/dht/client.scm
index 9d37f0f..59f07d7 100644
--- a/gnu/gnunet/dht/client.scm
+++ b/gnu/gnunet/dht/client.scm
@@ -677,8 +677,7 @@ do anything if @var{server} has been permanently 
disconnected."
             (assert (block-type? type))
             (value->index type))))
 
-    ;; TODO(tests): Disable lingering by default, test linger?=#false
-    (define* (start-get! server query found #:key (linger? #true))
+    (define* (start-get! server query found #:key (linger? #false))
       "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.
@@ -695,9 +694,9 @@ 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}.
 
-When the boolean @var{linger?} is false, the search is automatically
-cancelled when the search object becomes unreachable according to the GC.
-TODO: implement this behaviour!"
+When the boolean @var{linger?} is false (this is the default), the search is
+automatically cancelled when the search object becomes unreachable according
+to the GC."
       ;; TODO: options, xquery ...
       (define id (fresh-id server))
       (define options 0) ; TODO: allow setting some options
diff --git a/tests/distributed-hash-table.scm b/tests/distributed-hash-table.scm
index 1cf6777..5509390 100644
--- a/tests/distributed-hash-table.scm
+++ b/tests/distributed-hash-table.scm
@@ -638,7 +638,9 @@ supported.  When @var{explode} is signalled, the connection 
is closed."
           (assert (equal? (sort responses <) (iota length/expected)))
           ;; TODO: cancel query
           (signal-condition! done)))
-       (start-get! server (make-a-query type round) found)
+       (define search (start-get! server (make-a-query type round) found
+                                 ;; Not testing cancellation on GC here.
+                                 #:linger? #true))
        (wait done))
      (define* (ping/pong* this-type other-type round)
        (when (< round N_ROUNDS)
@@ -767,7 +769,10 @@ supported.  When @var{explode} is signalled, the 
connection is closed."
                                                   (endianness big))))
                         (assert (not found?))
                         (set! found? #true)
-                        (loop (+ round 1))))
+                        (loop (+ round 1)))
+                      ;; Cancellation is tested elsewhere, don't automatically
+                      ;; cancel.
+                      #:linger? #true)
           (signal-condition! done)))
      (let loop ((round 0))
        (define key-s (make-slice/read-write (sizeof /hashcode:512 '())))
@@ -795,7 +800,9 @@ supported.  When @var{explode} is signalled, the connection 
is closed."
        (start-get! server query (lambda (a-result)
                                  (wait search-defined)
                                  (stop-get! search)
-                                 (signal-condition! done))))
+                                 (signal-condition! done))
+                  ;; The 'found' callback is responsible for cancellation.
+                  #:linger? #true))
      (signal-condition! search-defined)
      (put! server (datum->insertion datum))
      (wait done)
@@ -808,7 +815,9 @@ supported.  When @var{explode} is signalled, the connection 
is closed."
      (define server (connect config))
      (define datum (make-a-datum))
      (define query (make-query (datum-type datum) (datum-key datum)))
-     (define search (start-get! server query (lambda (foo) (values))))
+     (define search (start-get! server query (lambda (foo) (values))
+                               ;; Not testing cancellation on GC here.
+                               #:linger? #true))
      (let loop ((n 0))
        (when (< n 40)
         (stop-get! search)
@@ -858,6 +867,9 @@ supported.  When @var{explode} is signalled, the connection 
is closed."
        ;; that @var{server} remembered to start the search again!).
        (put! server (datum->insertion datum))
        (wait found/condition)
+       ;; Explicitely cancel 'search' such that it is not cancelled too
+       ;; early due to GC.
+       (stop-get! search)
        #true))))
 
 (test-end)

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