[gnunet-scheme] 191/324: doc: Document message queue error handling.

[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 7e98a1b38547c16e2babbd3faee2b9c3cbccef1d
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Fri Aug 20 17:10:16 2021 +0200

    doc: Document message queue error handling.
    
    * doc/scheme-gnunet.tm (Error handler): New section.
---
 doc/scheme-gnunet.tm | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 7157d0b..760855f 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -254,6 +254,54 @@
     \ \ (connect/fibers config "nse" (message-handlers) error-handler))
   </scm-code>
 
+  <subsection|Error handler>
+
+  The message queue implementation usually just sends and receives messages,
+  but some exceptional situations cannot be communicated with
+  <scm|send-message!> or <scm|inject-message!>.<space|1em>For those, there is
+  the <scm|inject-error!> procedure.<space|1em>This variadic procedure
+  accepts a message queue to inject the error into, a
+  <with|font-shape|italic|key> (usually a symbol) describing the exceptional
+  situation and rest arguments.<space|1em>It calls the
+  <with|font-shape|italic|error handler> of the message queue with the key
+  and rest arguments.<space|1em>The following errors can currently be
+  reported by the built-in message queue implementations:
+
+  <\explain>
+    <scm|connection:connected>
+  <|explain>
+    The connection to the server has been established.
+  </explain>
+
+  <\explain>
+    <scm|input:regular-end-of-file>
+  </explain|The connection has been closed by the
+  server.<space|1em><todo|technically, this only means the write end has been
+  closed from the servers' POV.<space|1em>The read part might still be open
+  \V or is that only for pipes? \V TODO>>
+
+  <\explain>
+    <scm|input:premature-end-of-file>
+  </explain|The connection was closed by the server while a message was still
+  being read.<space|1em>This can happen if the server was stopped while it
+  was still sending the rest of the message.>
+
+  <\explain>
+    <scm|input:overly-small> <var|type> <var|size>
+  </explain|The mesage size in the header was smaller than the minimal
+  message size.<space|1em>Sometimes, but not always, the message type
+  <var|type> and message size <var|size> are available (as exact
+  naturals).<space|1em>When they are not available, <var|type> and <var|size>
+  are <scm|#false> instead.<space|1em>This can only happen if the server or
+  connection to the server is buggy.>
+
+  <todo|errors for no message handler and malformed messages>
+
+  Consider automatically reconnecting after
+  <scm|<scm|input:regular-end-of-file>> and
+  <scm|<scm|input:premature-end-of-file>>, to allow the server to restart
+  without having to manually restart every individual application.
+
   TODO information about message handlers, error handler <text-dots>
 
   <section|Estimation of the size of the network>

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