[gnunet-scheme] 235/324: doc: Document how errors and received/sent messages are ordered.

[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 9a809b8eb2cc9d3e6a47a0c8f463b078fcc8f30c
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Sep 6 15:22:26 2021 +0200

    doc: Document how errors and received/sent messages are ordered.
    
    * doc/scheme-gnunet.tm (Ordering of injected errors and messages and
      sent messages): New section, documenting how injected errors,
      injected messages, sent messages and invocations of notify-sent
      handlers are ordered with respect to each other.
---
 doc/scheme-gnunet.tm | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index e43e76c..b2dbd56 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -478,7 +478,54 @@
   <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>
+  <subsection|Ordering of injected errors and messages and sent messages>
+
+  This section describes how injected errors and messages and sent messages
+  are ordered with respect to each other in the default message queue
+  implementation.<space|1em>Messages are handled or corresponding
+  <scm|logic:no-handler> or <scm|logic:ill-formed> errors are injected in the
+  order that the messages are received.<space|1em>Before messages are read,
+  <scm|connection:connected> is injected.<space|1em>This error is injected at
+  most once.
+
+  <em|Soon> after all messages are read (and therefore
+  <with|font-shape|italic|soon> after all handled messages or corresponding
+  errors), the error <scm|input:regular-end-of-file>,
+  <scm|input:overly-small> or <scm|input:premature-end-of-file> is
+  injected.<space|1em>Only one of those errors can be injected for the entire
+  lifetime of the message queue.
+
+  Be aware that <em|soon> is not <em|immediate> here!<space|1em>For example,
+  it is possible for a message to be received, the port closed, a message
+  queued for sending, the closing of the port being detected by the write
+  fiber, <scm|input:regular-end-of-file> being injected from the write fiber
+  and the read fiber handling the received message, and the read fiber
+  exiting because the port is closed, in that order.
+
+  Messages are sent (and received on the other side) in the order they were
+  enqueued for sending.<space|1em>Likewise, the notify-sent callback of
+  enqueued messages are called in order.<space|1em>If the notify-sent
+  callback is called, it is before the message is received by the other
+  side.<space|1em>The message and its notify-sent callback are only received
+  by the other side and called after the message has been injected and
+  <scm|connection:connected> has been injected.<space|1em>It is possible for
+  the notify-sent callback to be called without the message being received by
+  the other side, e.g. if the port was closed during the notify-sent
+  callback.
+
+  If a message is received by the other side, all previously-sent messages
+  have be received before.<space|1em>If a notify-sent callback is invoked,
+  all notify-sent callbacks of previous messages have been invoked before,
+  except the messages that are eventually cancelled.
+
+  The errors <scm|logic:no-handler> and <scm|logic:ill-formed> are not fatal:
+  later messages can still be read and handled.
+
+  <todo|I/O errors>
+
+  <todo|disconnecting>
+
+  <todo|envelopes>
 
   <section|Estimation of the size of the network>
 

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