[gnunet-scheme] 02/05: doc: Document ‘send-message!’ and ‘priority-preferences’.

[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 1f6ddc48151d5ad47389eb38b901f190c97c4f10
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Sun Feb 6 13:00:51 2022 +0000

    doc: Document ‘send-message!’ and ‘priority-preferences’.
    
    * doc/service-communication.tm (Sending messages): New section.
    * NEWS: Note existence of new section.
---
 NEWS                         |  1 +
 doc/scheme-gnunet.tm         |  2 +-
 doc/service-communication.tm | 52 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index ced0881..2425898 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,7 @@
      a little more self-documenting and understandable.
    - Likewise, a new ‘c-type’ property has been defined, making
      cross-referencing between Scheme and C sources simpler.
+   - ‘send-message!’ and ‘priority-preferences’ are documented.
 * Changes since 0.1
 ** Features
    - A DHT client! (gnu gnunet dht client), documented in the manual
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 0f73fd1..45b52bc 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -7,7 +7,7 @@
   manual>|<doc-author|<author-data|<author-name|Maxime
   Devos>|<author-email|maximedevos@telenet.be>>>>
 
-  Copyright \<#A9\> 2021, 2022 GNUnet e.V.
+  Copyright \<#A9\> 2012-2016, 2021, 2022 GNUnet e.V.
 
   Permission is granted to copy, distribute and/or modify this document under
   the terms of the GNU Free Documentation License, Version 1.3 or any later
diff --git a/doc/service-communication.tm b/doc/service-communication.tm
index 056be14..c3c36a1 100644
--- a/doc/service-communication.tm
+++ b/doc/service-communication.tm
@@ -160,6 +160,58 @@
 
   <todo|how to define new message types>
 
+  <section|Sending messages>
+
+  Messages can be sent with the <scm|send-message!><index|send-message!>
+  procedure, which can be called as <scm|(send-message! <var|mq>
+  <var|message> #:priority <var|priority>)>, where <var|mq> is the message
+  queue and <var|message> is the message to send as a readable bytevector
+  slice. This is an asynchronuous operation, so this procedure can return
+  before the service has processed the message.
+
+  Depending on the transport, it might be possible for messages to be lost or
+  received out-of-order. Some transports allow to explicitely allow messages
+  to be lost or received out-of-order and would by default retransmit lost
+  messages and reorder out-of-order messages; this behaviour can to a degree
+  be controlled by setting the <dfn|priority-preference> flags.
+
+  These flags are not absolute, e.g. even if reliable transmission is
+  requested, it is possible that the transport fail to transmit the message.
+  The exact behaviour is transport-dependent!
+
+  <\description>
+    <item*|<scm|pref:unreliable>>Unreliable delivery is acceptable.
+
+    <item*|<scm|pref:low-latency>>Low latency is desired, this cannot be
+    meaningfully combined with <scm|pref:cork-allowed>.
+
+    <item*|<scm|pref:cork-allowed>>The transmission of a message can be
+    delayed to combine this message with other messages into a larger
+    transmission with less per-message overhead.
+
+    <item*|<scm|pref:good-throughput>>High bandwith is desired; the method
+    chosen for transmission should focus on overall throughput.
+
+    <item*|<scm|pref:out-of-order>>Out-of-order delivery is acceptable.
+  </description>
+
+  These flags can be combined into a numeric value with the macro
+  <scm|prio-prefs> from <scm|(gnu gnunet mq prio-prefs)>; the following code
+  defines <var|x> as the numeric value of the flags <scm|pref:unreliable> and
+  <scm|pref:out-of-order>:
+
+  <\scm>
+    (import (gnu gnunet mq prio-prefs))
+
+    (define x (prio-prefs pref:unreliable pref:out-of-order))
+  </scm>
+
+  This numeric priority-preference can be passsed to <scm|send-message!> as
+  the optional <var|priority> keyword argument of <scm|send-message!>. The
+  transport of <scm|connect/fibers> is always reliable and in-order.
+  <todo|notify-sent! callbacks><todo|cancellation><todo|queue size limits,
+  <scm|%suspicious-length>>
+
   <section|Error handler><index|error handler>
 
   The message queue implementation usually just sends and receives messages,

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