[gnunet-scheme] 06/08: doc/typeclasses: Document cisw types.

[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 3cb4d0007ad2c0a130348ab398c11965a02be8bb
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Wed Feb 1 15:40:47 2023 +0100

    doc/typeclasses: Document cisw types.
    
    This will simplify some other documentation later.
---
 doc/typeclasses.tm | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/doc/typeclasses.tm b/doc/typeclasses.tm
index 1f92061..f0430cf 100644
--- a/doc/typeclasses.tm
+++ b/doc/typeclasses.tm
@@ -39,6 +39,42 @@
   <\todo>
     todo
   </todo>
+
+  <section|Cooperative immutable slice wrappers (<acronym|cisw>)
+  <index|cisw><index|cooperative immutable slice wrapper>><label|cisw>
+
+  Records in Scheme-GNUnet often contain bytevector slices. When constructing
+  such a record, it would be inefficient to copy the whole bytevector slice.
+  As such, constructors of such record types typically don't do that, then.
+  At the same time, it usually is expected that the record is fully
+  immutable, and hence that the contents of the slices it contains don't
+  change over time. However, sometimes the slices do change over time so a
+  copy needs to made even if it is somewhat inefficient.
+
+  Therefore, these record types have two constructors: a constructor
+  conventionally named <scm|type-name/share> that does not make a copy and
+  requires that the slices are unmodified as long as the constructed object
+  remains in use, and a constructor conventionally named <scm|type-name> that
+  does make a copy and does not impose such requirements.
+
+  Sometimes, you receive a record that is only valid for a limited duration,
+  because afterwards the slices will be modified. To extend the duration, it
+  then is required to make a <em|copy> of the record that contains a copy of
+  the bytevector slices, and use the copy instead of the original. Procedures
+  for making such copies are conventionally named <scm|copy-type-name>, can
+  be called as <scm|(copy-type-name <var|original-record>)> and return the
+  copy.
+
+  These kind of record types are called <acronym|cisw> in Scheme-GNUnet. You
+  can contribute to Scheme-GNUnet by finding a better acronym.
+
+  As the records are immutable, field accessors for slices will always return
+  a read-only bytevector slice, even if a read-write bytevector slice was
+  passed to the constructor and even if the copying constructor was used.
+
+  Because bytevector slices cannot be compared with <scm|equal?>, the same
+  holds for <acronym|cisw> types. Instead, <acronym|cisw> types define their
+  own equality procedures, conventionally named <scm|type-name=?>.
 </body>
 
 <\initial>

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