[gnunet-scheme] 57/324: mq: define priority and preference values

[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 e154452a5844af3affd2c9229c49dd1ad815bfa9
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Thu Jan 28 14:37:51 2021 +0100

    mq: define priority and preference values
    
    * gnu/gnunet/util/mq-enum.scm
      (priority-preference, priority-preference?): new enum,
      with values ‘prio:best-effort’, ‘prio:urgent’,
      ‘pref:unreliable’, ‘pref:low-latency’, ‘pref:cork-allowed,
      ‘pref:goodput’ and ‘pref:out-of-order’.
    * gnu/gnunet/util/mq.scm
      (prio-prefs->integer, prio-pref:?, prio-pref:prio)
      (prio->integer): define new procedures.
      (PRIORITY_MASK): new constant.
---
 gnu/gnunet/util/mq-enum.scm | 97 ++++++++++++++++++++++++++++++++++++++++++++
 gnu/gnunet/util/mq.scm      | 98 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 195 insertions(+)

diff --git a/gnu/gnunet/util/mq-enum.scm b/gnu/gnunet/util/mq-enum.scm
new file mode 100644
index 0000000..5d5e7d8
--- /dev/null
+++ b/gnu/gnunet/util/mq-enum.scm
@@ -0,0 +1,97 @@
+;; This file is part of scheme-GNUnet.
+;; Copyright (C) 2012-2016 GNUnet e.V.
+;; Copyright (C) 2021 Maxime Devos
+;;
+;; scheme-GNUnet is free software: you can redistribute it and/or modify it
+;; under the terms of the GNU Affero General Public License as published
+;; by the Free Software Foundation, either version 3 of the License,
+;; or (at your option) any later version.
+;;
+;; scheme-GNUnet is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; Affero General Public License for more details.
+;;
+;; You should have received a copy of the GNU Affero General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+;;
+;; SPDX-License-Identifier: AGPL3.0-or-later
+
+;; Work around self-references.
+;; (enum-value ENUM sym) cannot be used in the
+;; same module where ENUM is defined, as
+;; when expanding enum-value, the module where
+;; ENUM is loaded first.
+(define-library (gnu gnunet util mq-enum)
+  (export priority-preference priority-preference?)
+  (import (gnu extractor enum))
+  (begin
+    (define-enumeration (priority-preference priority-preference?)
+      (#:documentation
+       "Per envelope preferences and priorities.
+This is to be used as a bit set, e.g. using @code{prio-pref->integer}
+and @code{integer->prio-pref}.  Priority-preferences are usually
+passed as integers to avoid conversion hence and forth.")
+      (#:max 8)
+      (#:known
+       (value
+       (documentation "Best-effort traffic (i.e. CADET relay, DHT)")
+       (symbol prio:best-effort)
+       (index 0))
+       (value
+       (documentation "Urgent traffic (local peer, i.e. Conversation).")
+       (symbol prio:urgent)
+       (index 1))
+       (value (symbol pref:0)
+             (documentation "[Unassigned]")
+             (index 2))
+       (value (symbol pref:1)
+             (documentation "[Unassigned]")
+             (index 3))
+       (value
+       (symbol pref:unreliable)
+       (documentation
+        "Flag to indicate that unreliable delivery is acceptable.  This
+means TRANSPORT will not attempt to receive an
+acknowledgment. CORE will just pass this flag through.  CADET
+will use unreliable delivery if this flag is set.
+
+Note that even without this flag, messages may be lost by
+TRANSPORT and CORE.
+
+Thus, how \"strong\" the semantics of reliable delivery are depends
+on the layer!")
+       (index 4))
+       ;; FIXME spelling error in src/include/gnunet_mq_lib.h
+       (value
+       (symbol pref:low-latency)
+       (documentation
+        "Flag to indicate that low latency is important.  This flag must
+generally not be used in combination with
+pref:cork-allowed as it would be a contradiction.
+When this flags is set, the envelope may skip forward in the
+queue (depending on priority) and also TRANSPORT should attempt
+to pick a communicator with particularly low latency.")
+       (index 5))
+       (value
+       (symbol pref:cork-allowed)
+       (documentation
+        "Flag to indicate that CORKing is acceptable. This allows the
+receiver to delay transmission in hope of combining this message
+with other messages into a larger transmission with less
+per-message overhead.")
+       (index 6))
+       (value
+       (symbol pref:goodput)
+       ;; FIXME maybe rename to pref:good-throughput
+       (documentation
+        "Flag to indicate that high bandwidth is desired. This flag
+indicates that the method chosen for transmission should focus on
+overall goodput.  It rarely makes sense to combine this flag with
+pref:low-latency")
+       (index 7))
+       (value
+       (symbol pref:out-of-order)
+       (documentation
+        "Flag to indicate that out-of-order delivery is OK.")
+       (index 8))))))
diff --git a/gnu/gnunet/util/mq.scm b/gnu/gnunet/util/mq.scm
new file mode 100644
index 0000000..43cf932
--- /dev/null
+++ b/gnu/gnunet/util/mq.scm
@@ -0,0 +1,98 @@
+;; This file is part of scheme-GNUnet.
+;; Copyright (C) 2012-2016 GNUnet e.V.
+;; Copyright (C) 2021 Maxime Devos
+;;
+;; scheme-GNUnet is free software: you can redistribute it and/or modify it
+;; under the terms of the GNU Affero General Public License as published
+;; by the Free Software Foundation, either version 3 of the License,
+;; or (at your option) any later version.
+;;
+;; scheme-GNUnet is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; Affero General Public License for more details.
+;;
+;; You should have received a copy of the GNU Affero General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+;;
+;; SPDX-License-Identifier: AGPL3.0-or-later
+
+;; @author Florian Dold (GNUnet)
+;; @author Christian Grothoff (GNUnet)
+;; @author Maxime Devos (scheme-GNUnet)
+;;
+;; @brief General-purpose message queue
+(library (gnu gnunet util mq)
+  (export priority-preference priority-preference?
+         PRIORITY_MASK
+         prio-prefs->integer
+         prio-pref:?
+         prio-pref:prefs
+         prio-pref:prio
+         prio->integer)
+  (import (only (guile) compose)
+         (gnu gnunet util mq-enum)
+         (gnu extractor enum)
+         (srfi srfi-26)
+         (rnrs arithmetic bitwise)
+         (rnrs base))
+  (begin
+    (define (prio-prefs->integer . values)
+      "Given a list of priority-preference enum values,
+return its numeric value."
+      (apply bitwise-ior
+            (map (compose (cute expt 2 <>) value->index) values)))
+
+    (define (prio-pref:? integer flag)
+      "Is the flag @var{flag} (an enum value) set in
+the integer @var{integer}?"
+      (bitwise-bit-set? integer (value->index flag)))
+
+    (define (prio-pref:prefs integer)
+      "Given the numeric priority-preference value @var{integer},
+return its preferences as multiple of @code{priority-preference}
+enum values.  The priority bits are ignored."
+      (let-syntax
+         ((bit (syntax-rules ()
+                 ((_ name ...)
+                  `(,@(let ((flag (symbol-value priority-preference name)))
+                        (if (prio-pref:? integer flag)
+                            `(,flag)
+                            `()))
+                    ...)))))
+       (apply values
+              (bit pref:unreliable
+                   pref:low-latency
+                   pref:cork-allowed
+                   pref:goodput
+                   pref:out-of-order))))
+
+    ;; Bit mask to apply to extract the priority bits.
+    (define PRIORITY_MASK 4)
+
+    (define (prio-pref:prio integer)
+      "Given a numeric priority-preference value @var{integer},
+return its priority type as a symbol, i.e. one of
+@code{prio:background}, @code{prio:best-effort},
+@code{prio:urgent} or @code{prio:critical-control}.
+The preference bits are ignored."
+      (case (bitwise-and integer PRIORITY_MASK)
+       ((0) 'prio:background)
+       ((1) 'prio:best-effort)
+       ((2) 'prio:urgent)
+       ((3) 'prio:critical-control)))
+
+    (define (prio->integer sym)
+      "An inverse of @var{prio-pref:prio}, not adding any
+preference bits."
+      (case sym
+       ;; Lowest priority, i.e. background traffic (i.e. NSE, FS).
+       ;; This is the default!
+       ((prio:background) 0)
+       ((prio:best-effort) 1)
+       ((prio:urgent) 2)
+       ;; Highest priority, control traffic (i.e. CORE/CADET KX).
+       ((prio:critical-control) 3)
+       (else (assert #f))))))
+;; TODO the message queue itself
+

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