[gnunet-scheme] branch master updated (58b0a65 -> c0c1dff)

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a change to branch master
in repository gnunet-scheme.

    from 58b0a65  Merge branch 'server-unification'
     new c647c4d  bv-slice: Define read-only and write-only variants of 
bv-slice/read-write.
     new 7d21860  doc: Document how to construct bytevector slices.
     new ab704f8  bv-slice: Use new bv-slice/read-only bv-slice/write-only 
where appropriate.
     new 2bbca2f  bv-slice: Test capabilities of bv-slice/...
     new 68d0bb5  bv-slice: Add slice-slice to the index.
     new 75b8a7e  doc/bytevector-slices: Document the predicates.
     new 85da55d  doc/bytevector-slices: Document types supported by bytevector 
slices.
     new 298efcd  doc/bytevector-slices: Document slice-X-ref and slice-X-set!.
     new 6617149  doc/bytevector-slices: Document slice-X-ref and slice-X-set! 
more.
     new 03bdaed  NEWS: Mention the new bytevector slices documentation.
     new de4e42e  Merge branch 'bytevector-slices'
     new c0c1dff  tests/distributed-hash-table: Skip a to-be-investigated 
hanging test.

The 12 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 Makefile.am                      |   2 +-
 NEWS                             |   2 +
 doc/bytevector-slices.tm         | 174 +++++++++++++++++++++++++++++++++++++++
 doc/scheme-gnunet.tm             |   2 +
 examples/web.scm                 |  12 +--
 gnu/gnunet/crypto.scm            |   5 +-
 gnu/gnunet/mq-impl/stream.scm    |   8 +-
 gnu/gnunet/util/cmsg.scm         |   2 +-
 gnu/gnunet/utils/bv-slice.scm    |  15 ++--
 tests/bv-slice.scm               |  18 +++-
 tests/distributed-hash-table.scm |   3 +
 11 files changed, 218 insertions(+), 25 deletions(-)
 create mode 100644 doc/bytevector-slices.tm

diff --git a/Makefile.am b/Makefile.am
index f2a6bb1..0ddd706 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -237,7 +237,7 @@ TEXMACS_HTML_SETTINGS = \
 tm_fragments = \
   doc/configuration.tm doc/contributing.tm doc/distributed-hash-table.tm \
   doc/network-size-estimation.tm doc/network-structures.tm \
-  doc/service-communication.tm
+  doc/service-communication.tm doc/bytevector-slices.tm
 
 doc/scheme-gnunet.pdf: doc/scheme-gnunet.tm $(tm_fragments)
        $(TEXMACS_CONVERT) -c "$<" "$@" -q
diff --git a/NEWS b/NEWS
index 5efe13e..80546a0 100644
--- a/NEWS
+++ b/NEWS
@@ -16,6 +16,8 @@
    - For 'make-disconnect!', only a single argument was mentioned in the
      manual, but there were actually two (non-optional!) arguments.  This
      has been rectified.
+   - Bytevector slices ((gnu gnunet utils bv-slice)) are now documented in the
+     manual, in the chapter ‘Bytevector slices’, albeit not completely.
 * Changes since 0.2
 ** New functionality
    - New tools for writing services -- have a look at ‘Writing service
diff --git a/doc/bytevector-slices.tm b/doc/bytevector-slices.tm
new file mode 100644
index 0000000..e12f4ff
--- /dev/null
+++ b/doc/bytevector-slices.tm
@@ -0,0 +1,174 @@
+<TeXmacs|2.1>
+
+<project|scheme-gnunet.tm>
+
+<style|tmmanual>
+
+<\body>
+  <chapter|Bytevector slices><index|bytevector slices>
+
+  In Scheme, bytes are put in bytevectors. Often, when a procedure needs to
+  act on a bytevector, it does not need to act on the whole bytevector, but
+  only on a (contiguous) part of the bytevector. This can be accomplished by
+  passing the procedure position and length arguments, but this is prone to
+  errors such as incorrect bounds calculations.
+
+  To solve this, <dfn|bytevector slices> are implemented in <scm|(gnu gnunet
+  utils bv-slice)><index|(gnu gnunet utils bv-slice)>. A bytevector slice is
+  a structure referring to a bytevector, with a position inside the
+  bytevector and the length (in bytes) of the bytevector. They can be
+  accessed with <scm|slice-bv><index|slice-bv>,
+  <scm|slice-position><index|slice-position> and
+  <scm|slice-length><index|slice-length> respectively.
+
+  <\warning>
+    The first two procedures, <scm|slice-bv> and <scm|slice-position>, are
+    considered low-level \V it is intended to, at some point in the future,
+    replace them with a single pointer. Using them outside low-level code is
+    recommended against when alternatives are available.
+  </warning>
+
+  Bytevector slices also have a very limited <dfn|capability> system, to
+  avoid accidental writes when a slice should only be read and to avoid
+  accidental reads when a slice should only be written. However, this is not
+  a true capability model, as it can be circumvented by using <scm|slice-bv>
+  and <scm|bv-slice/read-write> (i.e., slices are forgable) and because the
+  only possible capabilities (read of write or read-write) are very
+  coarse-grained; it is impossible to refine it.
+
+  <section|Constructing bytevector slices>
+
+  <\explain>
+    <scm|(slice-slice <var|slice>)><index|slice-slice>
+
+    <scm|(slice-slice <var|slice> <var|offset>)>
+
+    <scm|(slice-slice <var|slice> <var|offset> <var|length>)>
+  <|explain>
+    Select a part of the bytevector slice <var|slice>, preserving
+    capabilities. Start at the byte at index <var|offset> in the old slice
+    and let the new slice have <var|length> as length.
+
+    If <var|offset> is absent, start at index 0. If <var|length> is absent,
+    select the whole remaining part of <var|slice>.
+
+    The new slice must remain within the old slice. If not, an error is
+    raised <todo|dedicated exception type>.
+  </explain>
+
+  <\explain>
+    <scm|slice/read-only><index|slice/read-only>,
+    <scm|slice/write-only><index|slice/write-only>,
+    <scm|slice/read-write><index|slice/write-only>
+  <|explain>
+    These procedures function exactly the same as <scm|slice-slice>, except
+    that the capabilities are changed to read-only, write-only and read-write
+    respectively. The old capabilities must be an upper bound on the new
+    capabilities; capabilities cannot be gained with these procedures. If the
+    new capabilities exceed the old capabilities, an
+    <scm|&missing-capabilities> exception is raised, with the
+    \<#2018\>what\<#2019\> field set to the symbol <scm|slice>.
+  </explain>
+
+  <\explain>
+    <scm|bv-slice/read-only><index|bv-slice/read-only>,
+    <scm|bv-slice/write-only><index|bv-slice/write-only>,
+    <scm|bv-slice/read-write><index|bv-slice/read-write>
+  <|explain>
+    These procedures behave like <scm|slice/read-only>,
+    <scm|slice/write-only> and <scm|slice/read-write>, except that as first
+    argument they accept a bytevector instead of a bytevector slice. They
+    also never raise a <scm|&missing-capabilities>.
+
+    <\warning>
+      In the future, <scm|bv-slice/write-only> and <scm|bv-slice/read-write>
+      could be modified to check if the bytevector is read-only or read-write
+      (bytevectors that are part of the program text may not be modified in
+      Guile Scheme).
+    </warning>
+  </explain>
+
+  <\explain>
+    <scm|(make-slice/read-write <var|length>)><index|make-slice/read-write>
+  </explain|Make a fresh, zero-initialised, read-write slice, of length
+  <var|length>.>
+
+  <section|Predicates>
+
+  <\explain>
+    <scm|(slice? <var|object>)>
+  <|explain>
+    Return <scm|#true> if <var|object> is a slice, <scm|#false> otherwise.
+  </explain>
+
+  <\explain>
+    <scm|(slice-readable? <var|slice>)>
+  </explain|Return <scm|#true> if the slice <var|slice> is readable,
+  <scm|#false> otherwise.>
+
+  <\explain>
+    <scm|(slice-writable? <var|slice>)>
+  </explain|Return <scm|#true> if the slice <var|slice> is writable,
+  <scm|#false> otherwise.>
+
+  <section|Reading / modifying bytevector slices>
+
+  To read the value at a (byte) index in the slice, the procedures
+  <scm|slice-X-ref><index|slice-X-ref> are used. Likewise, to set the value
+  at a certain byte index, the procedures
+  <scm|slice-X-set!><index|slice-X-set!> are used. <scm|X> must be one of the
+  following:
+
+  <\description>
+    <item*|<scm|u8><index|u8>, u16<index|u16>, u32<index|u32>,
+    u64<index|u64>>An unsigned 8-bit, 16-bit, 32-bit and 64-bit integer,
+    respectively. I.e., an (exact) integer in the (closed) range
+    <math|<around*|[|0,2<rsup|N>-1|]>>, where <math|N> is the number of bits.
+
+    <item*|s8<index|s8>, s16<index|s16>, s32<index|s32>, s64<index|s64>>A
+    signed 8-bit, 16-bit, 32-bit and 64-bit integer, respectively, encoded in
+    the <hlink|two's 
complement|https://en.wikipedia.org/wiki/Two%27s_complement>
+    representation. I.e., an (exact) integer in the (closed) range
+    <math|<around*|[|-2<rsup|N-1>,2<rsup|N-1>-1|]>>.
+
+    <item*|<scm|ieee-double><index|ieee-double>>A <hlink|floating-point
+    number|https://en.wikipedia.org/wiki/Floating-point>, in
+    <hlink|IEEE<index|IEEE> 
binary64/double<index|binary64><index|double>|https://en.wikipedia.org/wiki/Double-precision_floating-point_format>
+    format.
+  </description>
+
+  Except for <scm|u8> and <scm|s8>, <scm|slice-X-ref> can be called as
+  <scm|(slice-X-ref slice <var|index> <var|endian>)>, where <var|slice> is
+  the bytevector slice, <var|index> is the byte index into the slice and
+  <var|endian> is the <dfn|endianness> according to which the bytes of the
+  type are ordered. Endianness is part of <scm|(rnrs bytevectors>). For
+  communication over the network (including communication between clients and
+  services), big-endian (i.e., <scm|(endianness big)>) is almost always used
+  in GNUnet.
+
+  Except for <scm|u8> and <scm|s8>, <scm|slice-X-set!> can be called as
+  <scm|(slice-X-ref slice <var|index> <var|endian> <var|value>)>, where
+  <var|slice>, <var|index> and <var|endian> have the same meaning as for
+  <scm|slice-X-ref>, and <var|value> is the value to set it to.
+
+  <todo|out-of-bounds, range and capabilities exceptions, can <var|value> be
+  a exact for <scm|ieee-double>>
+
+  For <scm|u8> and <scm|s8>, there is only a single byte and hence there is
+  no endianness. As such, <scm|slice-u8-ref>, <scm|slice-u8-set!>,
+  <scm|slice-s8-ref> and <scm|slice-s8-set!> do not have an endianness
+  argument. Aside from that, they behave similarly to the other
+  <scm|slice-X-ref> and <scm|slice-X-set!> procedures.
+
+  <scm|slice-X-ref> requires the slice to be readable, if not, an appropriate
+  <scm|&missing-capabilities> exception is raised. Likewise,
+  <scm|slice-X-set!> requires the slice to be writable. Both require the part
+  of the slice that is being read to be in-bounds.
+</body>
+
+<\initial>
+  <\collection>
+    <associate|page-medium|paper>
+    <associate|save-aux|false>
+  </collection>
+</initial>
\ No newline at end of file
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 23fe51c..ac9b597 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -346,6 +346,8 @@
   and <cpp|GNUNET_STRINGS_string_to_data><index|GNUNET_STRINGS_string_to_data>
   functions in the C implementation.
 
+  <include|bytevector-slices.tm>
+
   <appendix|GNU Free Documentation License>
 
   <include|fdl.tm>
diff --git a/examples/web.scm b/examples/web.scm
index d2e4468..14811f9 100644
--- a/examples/web.scm
+++ b/examples/web.scm
@@ -140,14 +140,14 @@ for success is used."
 (define (decode/key encoding data)
   (match encoding
     ("utf-8-text"
-     (hash/sha512 (bv-slice/read-write (string->utf8 data))))
+     (hash/sha512 (bv-slice/read-only (string->utf8 data))))
     ;; TODO other encodings
     ))
 
 (define (decode/data encoding data)
   (match encoding
     ("utf-8-text"
-     (bv-slice/read-write (string->utf8 data))
+     (bv-slice/read-only (string->utf8 data))
      ;; TODO other encodings
      )))
 
@@ -193,7 +193,7 @@ for success is used."
   (set* '(header size) (slice-length s))
   (set* '(header type)
        (value->index (symbol-value message-type 
msg:cadet:command-line-traffic)))
-  (slice-copy! (bv-slice/read-write message)
+  (slice-copy! (bv-slice/read-only message)
               (slice-slice s (sizeof /:msg:cadet:command-line-traffic '())))
   (send-message! mq s)
   (pk 'p channel mq))
@@ -205,7 +205,7 @@ for success is used."
 
 (define (data->string slice)
   (define bv (make-bytevector (slice-length slice)))
-  (slice-copy! slice (bv-slice/read-write bv))
+  (slice-copy! slice (bv-slice/write-only bv))
   (define as-string (try-utf8->string bv))
   (or as-string (object->string bv)))
 
@@ -228,8 +228,8 @@ If incorrect, return @code{#false}. TODO more validation."
 (define (parameters->cadet-address parameters)
   (pk 'p parameters)
   (cadet:make-cadet-address
-   (bv-slice/read-write (string->eddsa-public-key (assoc-ref parameters 
"peer")))
-   (hash/sha512 (bv-slice/read-write (string->utf8 (assoc-ref parameters 
"port"))))))
+   (bv-slice/read-only (string->eddsa-public-key (assoc-ref parameters 
"peer")))
+   (hash/sha512 (bv-slice/read-only (string->utf8 (assoc-ref parameters 
"port"))))))
 
 (define (process-search-dht dht-server parameters)
   (define search-result)
diff --git a/gnu/gnunet/crypto.scm b/gnu/gnunet/crypto.scm
index c62b753..2a388fc 100644
--- a/gnu/gnunet/crypto.scm
+++ b/gnu/gnunet/crypto.scm
@@ -64,14 +64,13 @@ return a bytevector with the resulting hash."
     (define (hash-slice! algorithm slice to)
       "Hash the data in the readable bytevector slice @var{slice} and write the
 hash to the bytevector slice @var{to}."
-      (slice-copy! (bv-slice/read-write (hash-slice/bytevector algorithm 
slice))
+      (slice-copy! (bv-slice/read-only (hash-slice/bytevector algorithm slice))
                   to))
 
     (define (hash-slice algorithm slice)
       "Hash the data in the readable bytevector slice @var{slice} and return a
 fresh readable bytevector slice with the hash."
-      (slice/read-only
-       (bv-slice/read-write (hash-slice/bytevector algorithm slice))))
+      (bv-slice/read-only (hash-slice/bytevector algorithm slice)))
 
     (define (hasher! algorithm)
       (lambda (slice to)
diff --git a/gnu/gnunet/mq-impl/stream.scm b/gnu/gnunet/mq-impl/stream.scm
index 23129f4..ff22a88 100644
--- a/gnu/gnunet/mq-impl/stream.scm
+++ b/gnu/gnunet/mq-impl/stream.scm
@@ -35,8 +35,7 @@
                trigger-condition!)
          (only (gnu gnunet utils bv-slice)
                slice-bv slice-offset slice-length
-               slice-readable? bv-slice/read-write
-               slice/read-only)
+               slice-readable? bv-slice/read-only)
          (only (gnu gnunet mq envelope)
                attempt-irrevocable-sent!)
          (only (gnu gnunet utils tokeniser)
@@ -136,10 +135,7 @@ This might or might not be correct.  In case of an I/O 
error, TODO.
 TODO closing message queues."
       (let^ ((! tok (make-tokeniser))
             (! (handle/message bv offset length)
-               (inject-message!
-                mq
-                (slice/read-only
-                 (bv-slice/read-write bv offset length))))
+               (inject-message! mq (bv-slice/read-only bv offset length)))
             (! (return/overly-small type size)
                (values 'input:overly-small type size))
             (! (return/premature-eof)
diff --git a/gnu/gnunet/util/cmsg.scm b/gnu/gnunet/util/cmsg.scm
index 38e7257..57613a8 100644
--- a/gnu/gnunet/util/cmsg.scm
+++ b/gnu/gnunet/util/cmsg.scm
@@ -301,7 +301,7 @@ the vector @var{a}."
         (bv (make-bytevector size))
         ;; should not result in &control-data-too-small
         (written (write-ancillary-vector->control!
-                  (bv-slice/read-write bv)
+                  (bv-slice/write-only bv)
                   a)))
     (assert (= size written))
     bv))
diff --git a/gnu/gnunet/utils/bv-slice.scm b/gnu/gnunet/utils/bv-slice.scm
index d7418f8..8676c52 100644
--- a/gnu/gnunet/utils/bv-slice.scm
+++ b/gnu/gnunet/utils/bv-slice.scm
@@ -29,7 +29,7 @@
          slice-offset
          slice-length
          slice-slice
-         bv-slice/read-write
+         bv-slice/read-write bv-slice/read-only bv-slice/write-only
          make-slice/read-write
          slice-readable?
          slice-writable?
@@ -204,14 +204,17 @@ name for the slice, @var{permitted} the capabilities of 
the slice and
       ((obj offset length)
        (slice-slice (process-first-arg obj) offset length))))
 
-  (define bv-slice/read-write
+  (define (make-bv-slicer capability-bits)
     (slice-as-well
      (lambda (bv)
-      "Construct a read-write bytevector slice.  Mutations will change
-the bytevector in place."
+       ;; Construct a bytevector slice with @var{capabilities}.
+       ;; Mutations will change the bytevector in place.
       (assert (bytevector? bv))
-      (%make-slice bv 0 (bytevector-length bv)
-                  (bitwise-ior CAP_READ CAP_WRITE)))))
+      (%make-slice bv 0 (bytevector-length bv) capability-bits))))
+
+  (define bv-slice/read-only (make-bv-slicer CAP_READ))
+  (define bv-slice/write-only (make-bv-slicer CAP_WRITE))
+  (define bv-slice/read-write (make-bv-slicer (bitwise-ior CAP_READ 
CAP_WRITE)))
 
   (define (make-slice/read-write length)
     "Make a fresh, zero-initialised, read-write slice"
diff --git a/tests/bv-slice.scm b/tests/bv-slice.scm
index edaefbf..2deaefc 100644
--- a/tests/bv-slice.scm
+++ b/tests/bv-slice.scm
@@ -169,14 +169,14 @@
 (test-equal "slice to string, read-only"
   "#<slice (CAP_READ): 1 2 3>"
   (object->string
-   (slice/read-only (bv-slice/read-write #vu8(1 2 3)))))
+   (bv-slice/read-only #vu8(1 2 3))))
 
 ;; Make sure the lack of a read capability cannot be circumvented by
 ;; object->string.
 (test-equal "slice to string, write-only"
   "#<slice (CAP_WRITE) length: 3>"
   (object->string
-   (slice/write-only (bv-slice/read-write #vu8(1 2 3)))))
+   (bv-slice/write-only #vu8(1 2 3))))
 
 (test-missing-caps
  "source of slice-copy/read-write must be readable"
@@ -359,6 +359,20 @@
                (assert (not (slice-independent? y x)))))))))
     #true))
 
+
+;; Additional bv-slice/read-only, bv-slice/write-only, bv-slice/read-write
+;; tests.
+
+(test-assert "return value of bv-slice/read-only is read-only"
+  (let ((slice (bv-slice/read-only (make-bytevector 9))))
+    (and (slice-readable? slice) (not (slice-writable? slice)))))
+(test-assert "return value of bv-slice/write-only is write-only"
+  (let ((slice (bv-slice/write-only (make-bytevector 9))))
+    (and (not (slice-readable? slice)) (slice-writable? slice))))
+(test-assert "return value of bv-slice/read-write is read-write"
+  (let ((slice (bv-slice/read-write (make-bytevector 9))))
+    (and (slice-readable? slice) (slice-writable? slice))))
+
 (test-end "bv-slice")
 
 ;; ^ TODO: test other procedures
diff --git a/tests/distributed-hash-table.scm b/tests/distributed-hash-table.scm
index 9453873..4c712fc 100644
--- a/tests/distributed-hash-table.scm
+++ b/tests/distributed-hash-table.scm
@@ -800,6 +800,9 @@ supported.  When @var{explode} is signalled, the connection 
is closed."
         (loop (+ n 1))))
      #true)))
 
+;; XXX hangs, maybe a bug in the DHT simulation?  Maybe best replace with a
+;; full DHT simulation.
+(test-skip 1)
 (test-assert "searches restarted after disconnect"
   (let ((stop-first-server (make-condition))
        (first-accepted (make-condition)))

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