[gnunet-scheme] 01/02: service-communication: Document 'garbage-collectable'.

[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 8c77340b0ca1aa59bb62666b8d22fdcf5c442167
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Jun 27 18:54:22 2022 +0000

    service-communication: Document 'garbage-collectable'.
    
    * doc/service-communication.scm (Testing service code): New section.
---
 doc/service-communication.tm | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/service-communication.tm b/doc/service-communication.tm
index 89c187d..97f4464 100644
--- a/doc/service-communication.tm
+++ b/doc/service-communication.tm
@@ -368,6 +368,50 @@
 
   Error messages are translated for the current locale.<todo|TODO actually
   call bindtextdomain>
+
+  <section|Testing service code>
+
+  The module <scm|(tests utils)> has \ a few procedures for testing service
+  code:
+
+  <\explain>
+    <scm|(garbage-collectable <var|service> <var|connect>)>
+  <|explain>
+    Test that the server object is properly garbage collectable \U i.e., make
+    sure that when the server object is not used anymore, all new fibers are
+    stopped after a GC. Due to Guile's conservative GC, this has some false
+    negatives (i.e., it passes when it shouldn't) and in theory false
+    positives (i.e., it fails when it shouldn't), although the test is
+    written in such a way that false positives should be rare.
+
+    Here, <var|service> is a string like <scm|"dht"> or <scm|"gns">. It is
+    required for generating the configuration file. <var|connect> is a
+    procedure that can be called as <scm|(connect config #:spawn _
+    #:connected _ #:disconnected _>), such as the <scm|connect> procedure
+    from (<todo|reference to DHT or NSE>.
+
+    This procedure returns a boolean value suitable for <scm|test-assert>.
+  </explain>
+
+  <todo|document more>
+
+  <\example>
+    In <verbatim|tests/distributed-hash-table.scm>, we have the following
+    tests:
+
+    <\scm-code>
+      (import (srfi srfi-64) (test utils) (gnu gnunet dht client)
+
+      (test-assert "(DHT) close, not connected --\<gtr\> all fibers stop, no
+      callbacks called"
+
+      \ \ (close-not-connected-no-fallbacks "dht" connect disconnect!))
+
+      (test-assert "(DHT) garbage collectable"
+
+      \ \ (garbage-collectable "dht" connect))
+    </scm-code>
+  </example>
 </body>
 
 <\initial>

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