[gnunet-scheme] 03/07: doc: Document hashcodes.

[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 d2716032d05fbe295154a770eff08c54e863244a
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Nov 21 09:25:22 2022 +0100

    doc: Document hashcodes.
    
    * doc/scheme-gnunet.tm (Hashcodes): New section.
---
 doc/scheme-gnunet.tm | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index ac9b597..5ef0851 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -346,6 +346,59 @@
   and <cpp|GNUNET_STRINGS_string_to_data><index|GNUNET_STRINGS_string_to_data>
   functions in the C implementation.
 
+  <section|Hashcodes>
+
+  In various places in GNUnet, and consequently Scheme-GNUnet,
+  <dfn|hashcodes><index|hashcode> are used. A hashcode is the SHA-512 hash of
+  some value, this way a hashcode identifies a value, up to (hopefully very
+  unlikely) hash collisions. There are two types of hashcodes in use in
+  GNUnet: <dfn|short hashcodes><index|short hashcode> and <dfn|long
+  hashcodes><index|long hashcode>, respectively of length 256 bits/32 bytes
+  and 512 bits/64 bytes. In Scheme-GNUnet, these are named
+  <dfn|hashcode:256><index|hashcode:256> and
+  <dfn|hashcode:512><index|hashcode:512> instead.
+
+  There are two kind of representations hashcodes: the record types
+  <scm|\<less\>hashcode:512\<gtr\>><index|\<less\>hashcode:512\<gtr\>> and
+  <scm|\<less\>hashcode:256\<gtr\>><index|\<less\>hashcode:256\<gtr\>> from
+  <scm|(gnu gnunet hashcode)><index|(gnu gnunet hashcode)> and the
+  corresponding <reference|network types>
+  <scm|/hashcode:512><index|/hashcode:521> and
+  <scm|/hashcode:512><index|/hashcode:256> from <scm|(gnu gnunet hashcode
+  struct)><index|(gnu gnunet hashcode struct)>. The module <scm|(gnu gnunet
+  hashcode struct)> is documented below.
+
+  <\explain>
+    <scm|(make-hashcode:512/share <var|slice>)><index|make-hashcode:512/share>
+  <|explain>
+    Make a <scm|hashcode:512> containing <var|slice> (a readable
+    <scm|/hashcode:512> bytevector slice). <var|slice> may not be mutated
+    while the constructed hashcode is in use. The contents can be retrieved
+    with <scm|hashcode:512-\<gtr\>slice>, as a readable <scm|/hashcode:512>
+    bytevector slice. It can be tested if an object is a <scm|hashcode:512>
+    with the predicate <scm|hashcode:512?>.
+  </explain>
+
+  <\explain>
+    <scm|(make-hashcode:256/share <var|slice>)><index|make-hashcode:256/share>
+  <|explain>
+    Make a <scm|hashcode:256> containing <var|slice> (a readable
+    <scm|/hashcode:256> bytevector slice). <var|slice> may not be mutated
+    while the constructed hashcode is in use. The contents can be retrieved
+    with <scm|hashcode:256-\<gtr\>slice>, as a readable <scm|/hashcode:256>
+    bytevector slice. It can be tested if an object is a <scm|hashcode:256>
+    with the predicate <scm|hashcode:256?>.
+  </explain>
+
+  <\explain>
+    <scm|(make-hashcode:512 <var|slice>)><index|make-hashcode:512>
+
+    <scm|(make-hashcode:256 <var|slice>)><index|make-hashcode:256>
+  </explain|This is equivalent to <scm|(make-hashcode:512 slice)> and
+  <scm|(make-hashcode:256 slice)>, except that it doesn't assume that
+  <var|slice> is not mutated. However, this imposes a small cost, as
+  <var|slice> will then be copied behind the scenes.>
+
   <include|bytevector-slices.tm>
 
   <appendix|GNU Free Documentation License>

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