[gnunet-scheme] 02/12: doc: Document how to construct bytevector slices.

[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 7d21860052ec769c5e315780355d3a7b56b770ec
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Sun Sep 11 18:05:48 2022 +0200

    doc: Document how to construct bytevector slices.
    
    * doc/bytevector-slices.tm: New chapter.
    * doc/scheme-gnunet.tm: Include the new chapter.
    * Makefile.amk (tm_fragments): Register new file.
---
 Makefile.am              |   2 +-
 doc/bytevector-slices.tm | 102 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/scheme-gnunet.tm     |   2 +
 3 files changed, 105 insertions(+), 1 deletion(-)

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/doc/bytevector-slices.tm b/doc/bytevector-slices.tm
new file mode 100644
index 0000000..eee6356
--- /dev/null
+++ b/doc/bytevector-slices.tm
@@ -0,0 +1,102 @@
+<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>)>
+
+    <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>.>
+</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>

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