[gnunet-scheme] branch master updated: cadet: Document close-channel!.

[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 9c8b278  cadet: Document close-channel!.
9c8b278 is described below

commit 9c8b27858542596a0263a3d652e31194b56bfe9c
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Sun Aug 28 18:40:04 2022 +0200

    cadet: Document close-channel!.
    
    * doc/cadet.tm (Connecting to an address): Document it.
    * gnu/gnunet/cadet/client.scm (close-channel!): Add a docstring.
---
 doc/cadet.tm                | 27 +++++++++++++++++++++++++++
 gnu/gnunet/cadet/client.scm | 13 +++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/doc/cadet.tm b/doc/cadet.tm
index 52e41fe..7517b3b 100644
--- a/doc/cadet.tm
+++ b/doc/cadet.tm
@@ -107,6 +107,33 @@
   channel and the procedure <scm|send-message!> can be used to send the
   message to the message queue (see: <reference|send-message!>).
 
+  When done with the channel, it should be <dfn|closed>, to save resources.
+  This is done with <scm|>the procedure 
<scm|close-channel!><index|close-channel!>:
+
+  <\explain>
+    <scm|(close-channel! <var|channel>)>
+  <|explain>
+    Close the channel <var|channel>. This is an asynchronuous operation, it
+    does not have an immediate effect. This is an idempotent operation,
+    closing a channel twice does not have any additional effect.
+
+    Any buffered messages before the call to the first <scm|close-channel!>,
+    will still be sent to the service (unless cancelled and until the
+    <scm|<scm|disconnect!>>). If messages requested reliable transport, then
+    CADET will still retransmit lost messages even though the channel is
+    closed or closing.
+
+    For buffered messages not before<footnote|Warning: in a concurrent
+    setting, \<#2018\>after' is not the same as \<#2018\>not
+    before\<#2019\>.> the call, it is unspecified whether they will still be
+    transmitted.
+  </explain>
+
+  Alternatively, you can do close the message queue of the channel with
+  <scm|(close-queue! (channel-message-queue <var|channel>))>, it's
+  equivalent. In fact, that's exactly how <scm|close-channel!> is
+  implemented!
+
   <section|Performing I/O \U GNUnet style>
 
   <section|Performing I/O \U BSD style>
diff --git a/gnu/gnunet/cadet/client.scm b/gnu/gnunet/cadet/client.scm
index d22264c..83234e9 100644
--- a/gnu/gnunet/cadet/client.scm
+++ b/gnu/gnunet/cadet/client.scm
@@ -524,6 +524,19 @@ received, it is passed to the appropriate handler."
     ;; TODO: call when mq is closed, maybe unify closing the message queue
     ;; and the channel?
     (define (close-channel! channel)
+      "Close the channel @var{channel}. This is an asynchronuous operation, it
+does not have an immediate effect. This is an idempotent operation, closing
+a channel twice does not have any additional effect.
+
+Any buffered messages before the call to the first @code{close-channel!},
+will still be sent to the service (unless cancelled and until the
+@code{disconnect!}). If messages requested reliable transport, then CADET will
+still retransmit lost messages even though the channel is closed or closing.
+
+For buffered messages not before (*) the call, it is unspecified whether they
+will still be transmitted.
+
+(*) Warning: in a concurrent setting, ‘after’ is not the same as ‘not before’."
       (assert (channel? channel))
       (maybe-send-control-message! (channel-server channel) 'close-channel!
                                   channel))

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