[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnunet-scheme] 04/04: doc: Populate the index.
|
From: |
gnunet |
|
Subject: |
[gnunet-scheme] 04/04: doc: Populate the index. |
|
Date: |
Thu, 03 Feb 2022 11:17:12 +0100 |
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 41305550f4bc0b0887d2908d3bb3f2865195b3cb
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Thu Feb 3 10:16:01 2022 +0000
doc: Populate the index.
Fixes: <https://notabug.org/maximed/scheme-gnunet/issues/21>.
* doc/scheme-gnunet.tm: Add things to the index, fix typos.
---
doc/scheme-gnunet.tm | 403 ++++++++++++++++++++++++++++-----------------------
1 file changed, 224 insertions(+), 179 deletions(-)
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 26d14ad..b55c294 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -215,10 +215,11 @@
A few patches to guile and guile-fibers are required (some bug fixes, some
extra functionality), see <verbatim|guix.scm>.
- Users of <hlink|GNU Guix|https://guix.gnu.org> can run <shell|guix
- environment -l guix.scm> in the checkout to create an environment where
- these dependencies are all present.<space|1em>Scheme-GNUnet uses the
- standard GNU build system, so to build Scheme-Gnunet, you only need to run
+ Users of <hlink|GNU Guix|https://guix.gnu.org><index|Guix> can run
+ <shell|guix environment -l guix.scm> in the checkout to create an
+ environment where these dependencies are all
+ present.<space|1em>Scheme-GNUnet uses the standard GNU build system, so to
+ build Scheme-Gnunet, you only need to run
<\shell-code>
autoreconf -vif
@@ -240,7 +241,7 @@
$ guile -L . -C . -l examples/nse-web.scm
</shell-code>
- <subsection|Authenticating new source code>
+ <subsection|Authenticating new source code><index|authentication>
When GNU Guix is present, after pulling the latest Scheme-GNUnet commit,
the following command can be run to verify it is authentic:
@@ -351,12 +352,13 @@
<chapter|Configuration>
There are a number of modules for accessing GNUnet
- configurations.<space|1em>Firstly, there is <scm|(gnu gnunet config db)>,
- which is the module library code would typically use.<space|1em>For
- testing, one can create an empty configuration with the procedure
- <scm|hash-\<gtr\>configuration> from that module and <scm|make-hashtable>
- from <scm|(rnrs hashtables)>, using <scm|hash-key> as hash function and
- <scm|key=?> as comparison function:
+ configurations<index|configuration>.<space|1em>Firstly, there is <scm|(gnu
+ gnunet config db)><index|(gnu gnunet config db)>, which is the module
+ library code would typically use.<space|1em>For testing, one can create an
+ empty configuration with the procedure
<scm|hash-\<gtr\>configuration><index|hash-\<gtr\>configuration>
+ from that module and <scm|make-hashtable> from <scm|(rnrs hashtables)>,
+ using <scm|hash-key><index|hash-key> as hash function and
+ <scm|key=?><index|key=?> as comparison function:
<\scm-code>
(import (gnu gnunet config db)
@@ -374,7 +376,8 @@
<verbatim|nse>, to configure the network-size estimation service:
<\scm-code>
- (set-value! identity config "nse" "UNIXPATH" "/tmp/nse.sock")
+ (set-value! identity config "nse" "UNIXPATH"
+ "/tmp/nse.sock")<index|set-value!>
(set-value! number-\<gtr\>string config "cadet" "MAX_ROUTES" 5000)
@@ -384,7 +387,8 @@
Now read these values back:
<\scm-code>
- (read-value value-\<gtr\>file-name config "nse" "UNIXPATH")
+ (read-value value-\<gtr\>file-name config "nse"
+ "UNIXPATH")<index|read-value>
;; -\<gtr\> /tmp/nse.sock
@@ -394,7 +398,8 @@
</scm-code>
What if the configuration doesn't have a value for the specified section
- and key?<space|1em>Then an <scm|&undefined-key-error> results:
+ and key?<space|1em>Then an
<scm|&undefined-key-error><index|&undefined-key-error>
+ results:
<\scm-code>
(read-value value-\<gtr\>natural config "kated" "MAX_ROUTES")
@@ -415,18 +420,20 @@
<section|Locating configuration files>
There are two \U possibly non-existent \U configuration files: the
- <with|font-shape|italic|user> configuration and the
- <with|font-shape|italic|system> configuration.<space|1em>The
+ <with|font-shape|italic|user> configuration<subindex|configuration|user>
+ and the <with|font-shape|italic|system>
+ configuration<subindex|configuration|system>.<space|1em>The
<with|font-shape|italic|system> configuration typically contains the paths
for services like NSE, CORE, <text-dots><space|1em>A user may choose not to
use the services by the system and instead use their own.<space|1em>To do
so, the user needs to override the paths in the
<with|font-shape|italic|user> configuration.<space|1em><todo|defaults?> The
- module <scm|(gnu gnunet config fs)> is responsible for determining the
- location of the configuration files to load and actually load configuration
- files.<space|1em>For determining the location of the configuration files,
- the procedures <scm|locate-user-configuration> and
- <scm|locate-system-configuration> can be used.
+ module <scm|(gnu gnunet config fs)><index|(gnu gnunet config fs)> is
+ responsible for determining the location of the configuration files to load
+ and actually load configuration files.<space|1em>For determining the
+ location of the configuration files, the procedures
+ <scm|locate-user-configuration> and <scm|locate-system-configuration> can
+ be used.
<\warning>
The C implementation's mechanism for user-system separation seems to work
@@ -434,7 +441,7 @@
</warning>
<\explain>
- <scm|(locate-user-configuration <scm|#:getenv=getenv>)>
+ <scm|(locate-user-configuration
<scm|#:getenv=getenv>)><index|locate-user-configuration>
<|explain>
This procedure determines the location of the user configuration file, as
a string, or <scm|#false> if it could not be determined.<space|1em>If the
@@ -445,21 +452,22 @@
of the file <verbatim|gnunet.conf> in the directory
<shell|$XDG_CONFIG_HOME> is returned.<space|1em>If the environment
variable is not set, the location of the file at
- <verbatim|.config/gnunet.conf> in the home directory specified by the
- environment variable <verbatim|HOME> is returned, if that environment
- variable exists.<space|1em>If both are unset, <scm|#false> is returned.
+ <verbatim|.config/gnunet.conf><index|~/.config/gnunet.conf> in the home
+ directory specified by the environment variable <verbatim|HOME> is
+ returned, if that environment variable exists.<space|1em>If both are
+ unset, <scm|#false> is returned.
The values of environment variables is determined with the procedure
<scm|getenv>.
</explain>
<\explain>
- <scm|(locate-system-configuration)>
+ <scm|(locate-system-configuration)><index|locate-system-configuration>
<|explain>
This procedure determines the location of the system configuration file,
as a string.
- Currently, this is always <verbatim|/etc/gnunet.conf>.
+ Currently, this is always
<verbatim|/etc/gnunet.conf><index|/etc/gnunet.conf>.
</explain>
<section|Loading configuration files>
@@ -470,7 +478,8 @@
be used to determine all section-key-values triples in the configuration.
<\explain>
- <scm|(load-configuration/port! <var|set-value!> <var|port>)>
+ <scm|(load-configuration/port! <var|set-value!>
+ <var|port>)><index|load-configuration/port!>
<|explain>
Load the configuration from the input port <var|port>.
@@ -481,15 +490,16 @@
<todo|document expansible objects><todo|error reporting>
</explain>
- A variable assignment <verbatim|[section] key=value${var}> can refer to
- variables defined in the <verbatim|PATHS> section and variables from the
- environment.<space|1em>The previously described procedure
- <scm|load-configuration/port!> will <em|not> expand such assignements. \ To
- expand variable assignments, use the procedure
+ A variable assignment<index|variable assignment> <verbatim|[section]
+ key=value${var}> can refer to variables defined in the <verbatim|PATHS>
+ section and variables from the environment.<space|1em>The previously
+ described procedure <scm|load-configuration/port!> will <em|not> expand
+ such assignements. \ To expand variable assignments, use the procedure
<scm|make-expanded-configuration> instead.
<\explain>
- <scm|(make-expanded-configuration <var|load!> #:getenv=<var|getenv>)>
+ <scm|(make-expanded-configuration <var|load!>
+ #:getenv=<var|getenv>)><index|make-expanded-configuration>
<|explain>
Make a configuration object.<space|1em>To populate the configuration, all
the procedure <var|load!> with a <scm|set-value!> procedure as expected
@@ -502,7 +512,8 @@
configuration, use the thunk <scm|load-configuration>:
<\explain>
- <scm|(load-configuration #:getenv=<var|getenv> #:files=<text-dots>)>
+ <scm|(load-configuration #:getenv=<var|getenv>
+ #:files=<text-dots>)><index|load-configuration>
</explain|Load the defaults, the system configuration and the user
configuration and return the resulting configuration object.<space|1em>The
list of files to load can be overriden by setting the undocumented
@@ -681,28 +692,30 @@
<chapter|Communication with services>
- To connect with a GNUnet service \V this applies to both the C and Scheme
- implementation, the GNUnet service must bind a local domain
- socket<\footnote>
+ To connect with a GNUnet service<index|services> \V this applies to both
+ the C and Scheme implementation, the GNUnet service must bind a local
+ domain socket<\footnote>
The C implementation supports Internet sockets as well.
</footnote> somewhere on the file system and the client (possibly another
service) must connect to it.<space|1em>Connections to a service can be made
- with the <scm|connect/fibers> procedure from <scm|(gnu gnunet mq-impl
- stream)>, like this:
+ with the <scm|connect/fibers><index|connect/fibers> procedure from
+ <scm|(gnu gnunet mq-impl stream)><index|(gnu gnunet mq-impl stream)>, like
+ this:
<\scm-code>
(define mq (connect/fibers config "nse" handlers error-handler))
</scm-code>
- <section|Asynchronuously connecting>
+ <section|Asynchronuously connecting><index|connecting to services>
This is an asynchronuous operation: it will \<#2018\>complete\<#2019\>
immediately and the connection will actually be formed in the
background.<space|1em>When the connection has actually be formed, the
- <scm|error-handler> is called with the symbol
- <scm|connection:connected>.<space|1em>To demonstrate, the following code
- asynchronuously connects to the NSE service, and prints the text
- <scm|"connected!"> when the connection has actually been formed.
+ <scm|error-handler><index|error-handler> is called with the symbol
+ <scm|connection:connected><index|connection:connected>.<space|1em>To
+ demonstrate, the following code asynchronuously connects to the NSE
+ service, and prints the text <scm|"connected!"> when the connection has
+ actually been formed.
<\scm-code>
;; XXX test this, explain 'config' ...
@@ -730,7 +743,7 @@
corresponding message handler is invoked.<space|1em>Message handlers can be
constructed with the <scm|message-handler><index|message-handler> macro and
the <scm|make-message-handler><index|make-message-handler> procedure from
- <scm|(gnu gnunet nse client)>, as follows:
+ <scm|(gnu gnunet mq handler)>, as follows:
<\scm-code>
(import (gnu gnunet mq handler)
@@ -787,10 +800,11 @@
</scm-code>
As illustrated in the example code above, a message handler has four
- components: the <with|font-shape|italic|type> of message it handles, an
- <with|font-shape|italic|interposer> which will be explained later, the
- <with|font-shape|italic|verifier> deciding if a message is well-formed and
- the <with|font-shape|italic|handler procedure>.
+ components: the <with|font-shape|italic|type> of message<subindex|message
+ type|of handler> it handles, an
<with|font-shape|italic|interposer><index|interposer>
+ which will be explained later, the
<with|font-shape|italic|verifier><index|verifier>
+ deciding if a message is well-formed and the
+ <with|font-shape|italic|handler procedure><index|handler procedure>.
The verifier is passed a bytevector slice with the message and should
return <scm|#true> if the message is well-formed and <scm|#false> if it
@@ -810,14 +824,16 @@
<todo|document the message type database, various procedures>
- <section|Message type database>
+ <section|Message type database><subindex|message type|database>
- The module <scm|(gnu gnunet message protocols)> has a mapping of symbolic
- names of every message type known to scheme-GNUnet to their numeric
- value.<space|1em>To use it, the macro <scm|symbol-value> from <scm|(gnu
- extractor enum)> is required and possibly <scm|value-\<gtr\>index> as
- well.<space|1em>To determine the numeric value of the message type
- <scm|msg:nse:estimate>, one would write:
+ The module <scm|(gnu gnunet message protocols)><index|(gnu gnunet message
+ protocols)> has a mapping of symbolic names of every message type known to
+ scheme-GNUnet to their numeric value.<space|1em>To use it, the macro
+ <scm|symbol-value><index|symbol-value> from <scm|(gnu extractor
+ enum)><index|(gnu extractor enum)> is required and possibly
+ <scm|value-\<gtr\>index><index|value-\<gtr\>index> as well.<space|1em>To
+ determine the numeric value of the message type <scm|msg:nse:estimate>, one
+ would write:
<\scm-code>
(define numeric-type
@@ -830,32 +846,32 @@
<todo|how to define new message types>
- <section|Error handler>
+ <section|Error handler><index|error handler>
The message queue implementation usually just sends and receives messages,
but some exceptional situations cannot be communicated with
<scm|send-message!> or <scm|inject-message!>.<space|1em>For those, there is
- the <scm|inject-error!> procedure.<space|1em>This variadic procedure
- accepts a message queue to inject the error into, a
- <with|font-shape|italic|key> (usually a symbol) describing the exceptional
- situation and rest arguments.<space|1em>It calls the
+ the <scm|inject-error!><index|inject-error!> procedure.<space|1em>This
+ variadic procedure accepts a message queue to inject the error into, a
+ <with|font-shape|italic|key><index|key> (usually a symbol) describing the
+ exceptional situation and rest arguments.<space|1em>It calls the
<with|font-shape|italic|error handler> of the message queue with the key
and rest arguments.<space|1em>The following errors can currently be
reported by the built-in message queue implementations:
<\explain>
- <scm|connection:connected>
+ <scm|connection:connected><index|connection:connected>
<|explain>
The connection to the server has been established.
</explain>
<\explain>
- <scm|connection:interrupted>
+ <scm|connection:interrupted><index|connection:interrupted>
</explain|The message queue has been closed before the connection to the
server could be established.>
<\explain>
- <scm|input:regular-end-of-file>
+ <scm|input:regular-end-of-file><index|input:regular-end-of-file>
<|explain>
The connection has been closed by the server.
@@ -868,13 +884,13 @@
</explain>
<\explain>
- <scm|input:premature-end-of-file>
+ <scm|input:premature-end-of-file><index|input:premature-end-of-file>
</explain|The connection was closed by the server while a message was still
being read.<space|1em>This can happen if the server was stopped while it
was still sending the rest of the message.>
<\explain>
- <scm|input:overly-small> <var|type> <var|size>
+ <scm|input:overly-small> <var|type> <var|size><index|input:overly-small>
</explain|The message size in the header was smaller than the minimal
message size.<space|1em>Sometimes, but not always, the message type
<var|type> and message size <var|size> are available (as exact
@@ -883,7 +899,7 @@
connection to the server is buggy.>
<\explain>
- <scm|logic:no-handler> <var|type> . <var|rest>
+ <scm|logic:no-handler> <var|type> . <var|rest><index|logic:no-handler>
<|explain>
The received message of type <var|type> (as an integer) does not have a
corresponding message handler.<space|1em><var|rest> is currently
@@ -891,7 +907,7 @@
</explain>
<\explain>
- <scm|logic:ill-formed> <var|type> . <var|rest>
+ <scm|logic:ill-formed> <var|type> . <var|rest><index|logic:ill-formed>
</explain|The received message of type (as an integer) is ill-formed
according to the message handler.<space|1em><var|rest> is currently
unspecified.>
@@ -953,53 +969,60 @@
<todo|envelopes>
- <section|Disconnecting>
+ <section|Disconnecting><index|disconnecting>
- A message queue can be closed with the <scm|close-queue!> procedure from
- <scm|(gnu gnunet mq)>.<space|1em>In the default message queue
- implementation, this asynchronuously closes the port and stops associated
- fibers.<space|1em>Closing ports when they won't be used anymore is
- important for limiting resource consumption, especially for servers that
+ A message queue can be closed with the <scm|close-queue!><index|close-queue!>
+ procedure from <scm|(gnu gnunet mq)>.<space|1em>In the default message
+ queue implementation, this asynchronuously closes the port and stops
+ associated fibers.<space|1em>Closing ports when they won't be used anymore
+ is important for limiting resource consumption, especially for servers that
can have many connections.<space|1em>Closing message queues is an
idempotent operation: closing a message queue twice is the same as closing
it once.<space|1em> If a message queue is closed before a connection could
- be formed, <scm|connection:interrupted> is injected instead of
- <scm|connection:connected> and <scm|connection:regular-end-of-file>.
+ be formed, <scm|connection:interrupted><index|connection:interrupted> is
+ injected instead of <scm|connection:connected> and
+ <scm|connection:regular-end-of-file>.
<section|Error reporting><label|sec:error reporting>
<index|error reporting>Errors can be reported with the procedure
<scm|report-error> from the module <scm|(gnu gnunet mq
- error-reporting)>.<space|1em>It can be called as <scm|(report-error key
- argument ...)>, e.g. <scm|(report-error 'logic:no-handler 3)>.<space|1em>By
- default, it reports the error to the current error port.<space|1em>If this
- is not desired, the output can be sent to another port by setting the
- parameter <scm|textual-error-reporting-port>.<space|1em>If textual error
- reporting is not desired, the parameter <scm|error-reporter> can be set to
- a procedure with the same interface as <scm|report-error>.<space|1em>Such a
- procedure could e.g. open a GUI dialog, sent the message to the system
- logger or ignore the error.
+ error-reporting)><index|(gnu gnunet mq error-reporting)>.<space|1em>It can
+ be called as <scm|(report-error key argument ...)>, e.g. <scm|(report-error
+ 'logic:no-handler 3)><index|report-error>.<space|1em>By default, it reports
+ the error to the current error port.<space|1em>If this is not desired, the
+ output can be sent to another port by setting the parameter
+
<scm|textual-error-reporting-port><index|textual-error-reporting-port>.<space|1em>If
+ textual error reporting is not desired, the parameter
+ <scm|error-reporter><index|error-reporter> can be set to a procedure with
+ the same interface as <scm|report-error>.<space|1em>Such a procedure could
+ e.g. open a GUI dialog, sent the message to the system logger or ignore the
+ error.
Error messages are translated for the current locale.<todo|TODO actually
call bindtextdomain>
<chapter|Estimation of the size of the network>
- <index|network size estimation>GNUnet has a service that roughly estimates
- the size of the network \U i.e., the number of peers.<space|1em>The module
- <scm|(gnu gnunet nse client)> can be used to interact with this
- service.<space|1em>The connection is made with the procedure <scm|connect>,
+ <index|network size estimation><index|NSE>GNUnet has a service that roughly
+ estimates the size of the network \U i.e., the number of
+ peers.<space|1em>The module <scm|(gnu gnunet nse client)><index|(gnu gnunet
+ nse client)> can be used to interact with this service.<space|1em>The
+ connection is made with the procedure <scm|connect><subindex|connect|NSE>,
which is accepts a <with|font-shape|italic|configuration> (see
<todo|reference>) and some optional keyword arguments.<space|1em>This
procedure can be called as <scm|(connect config #:updated updated
#:connected connected #:disconnected disconnected)>.<space|1em>It returns a
- <with|font-shape|italic|NSE server object>.
+ <with|font-shape|italic|NSE server object><index|NSE server
+ object><subindex|server object|NSE>.
The connection is made asynchronuously; the thunk <var|connected> will be
called when the connection has actually been made.<space|1em>Whenever a new
- estimate becomes available, the (optional) procedure <var|updated> is
- called with the new
<with|font-shape|italic|estimate>.<space|1em>Alternatively,
- the procedure <scm|estimate> can be called on the server object to return
+ estimate becomes available, the (optional) procedure
+ <var|updated><index|update procedure> is called with the new
+ <with|font-shape|italic|estimate><index|estimate
+ object>.<space|1em>Alternatively, the procedure
+ <scm|estimate><index|estimate> can be called on the server object to return
the latest available estimate.<space|1em>If the
<with|font-shape|italic|server object> doesn't have an estimate yet, that
procedure will return <scm|#false> instead of an estimate.
@@ -1007,31 +1030,32 @@
When the connection is lost, the (optional) thunk <var|disconnected> is
called and <scm|(gnu gnunet nse client)> will retry
connecting.<space|1em>To close the current connection, if any, and stop
- reconnecting, the idempotent procedure <scm|disconnect!> can be called on
- the server object.
+ reconnecting, the idempotent procedure
<scm|disconnect!><subindex|disconnect!|NSE>
+ can be called on the server object.
<todo|input, validation, I/O errors?>
The estimate object has a number of accessors:
<\explain>
- <scm|(estimate:logarithmic-number-peers <var|estimate>)>
+ <scm|(estimate:logarithmic-number-peers
+ <var|estimate>)><index|estimate:logarithmic-number-peers>
</explain|The base-2 logarithm of the number of peers (estimated), as a
positive flonum, possibly zero or infinite>
<\explain>
- <scm|(estimate:number-peers <var|estimate>)>
+ <scm|(estimate:number-peers <var|estimate>)><index|estimate:number-peeers>
</explain|The number of peers (estimated), as a flonum, at least <scm|1.0>
and possibly infinite.<space|1em>This is not necessarily an (inexact)
<scm|integer?>, as it is only an estimate.>
<\explain>
- <scm|(estimate:timestamp estimate)>
+ <scm|(estimate:timestamp estimate)><index|estimate:timestamp>
</explain|A timestamp when the estimate was made <todo|something about
epoch?>>
<\explain>
- <scm|(estimate:standard-deviation <var|estimate>)>
+ <scm|(estimate:standard-deviation
<var|estimate>)><index|estimate:standard-deviation>
<|explain>
The estimated standard deviation on the base-2 logarithm of peers,
calculated over the last 64 rounds, with the <math|<frac|N|N-1>>
@@ -1049,14 +1073,16 @@
<chapter|Accessing the DHT>
- GNUnet has a service that maintains a <em|distributed hash table>, mapping
- keys to values. The module <scm|(gnu gnunet dht client)> can be used to
- interact with the service. The connection can be made with the procedure
- <scm|connect>. It returns a <em|DHT server object>.
+ GNUnet has a service that maintains a <em|distributed hash
+ table><index|distributed hash table><index|DHT><index|R5N>, mapping keys to
+ values. The module <scm|(gnu gnunet dht client)><index|(gnu gnunet dht
+ client)> can be used to interact with the service. The connection can be
+ made with the procedure <scm|connect>. It returns a <em|DHT server
+ object><index|DHT server object><subindex|server object|DHT>.
<\explain>
<scm|(connect <var|config> <var|#:connected> <var|#:disconnected>
- <var|#:spawn-fiber>)>
+ <var|#:spawn-fiber>)><subindex|connect|DHT>
<|explain>
Connect to the DHT service, using the configuration <var|config>. The
connection is made asynchronuously; the optional thunk <var|connected> is
@@ -1067,7 +1093,7 @@
</explain>
<\explain>
- <scm|(disconnect! <var|server>)>
+ <scm|(disconnect! <var|server>)><subindex|disconnect!|DHT>
<|explain>
Asynchronuously disconnect from the DHT service and stop reconnecting,
even if not connected. This is an idempotent operation.
@@ -1078,17 +1104,19 @@
To insert data into the DHT, the DHT service needs various information \U
the key and the value, but also some other information. Likewise, when the
DHT service has found the datum, this information is available as well. A
- datum in the DHT is represented as a <em|datum object>. The object holding
- the information required for inserting something in the DHT is called an
- <em|insertion object>. Likewise, the information of searching for something
- in the DHT is in a <em|query object>. The result of a query is a <em|search
- result object>.
+ datum in the DHT is represented as a <em|datum object><index|datum object>.
+ The object holding the information required for inserting something in the
+ DHT is called an <em|insertion object><index|insertion object>. Likewise,
+ the information of searching for something in the DHT is in a <em|query
+ object><index|query object>. The result of a query is a <em|search result
+ object><index|search result object>.
These objects only hold information; creating them does not have any side
effects.
<\explain>
- <scm|(make-datum <var|type> <var|key> <var|value> <var|#:expiration>)>
+ <scm|(make-datum <var|type> <var|key> <var|value>
+ <var|#:expiration>)><index|make-datum>
<|explain>
Make a datum object of block type <var|type> (or its corresponding
numeric value), with key <var|key> (a readable <scm|/hashcode:512>
@@ -1097,31 +1125,36 @@
<var|expiration> is optional, see <reference|???>.
The numeric value of the block type can be retrieved with the accessor
- <scm|datum-type>. The accessors <scm|datum-key>, <scm|datum-value> and
- <scm|datum-expiration> return the key, value and expiration time
- respectively. It can be tested if an object is a datum object with the
- predicate <scm|datum?>.
-
- The length of <var|value> may be at most <scm|%max-datum-value-length>.
- If this bound is exceeded, an appropriate <scm|&overly-large-datum> and
- <scm|&who> condition is raised.
+ <scm|datum-type>. The accessors <scm|datum-key><index|datum-key>,
+ <scm|datum-value><index|datum-value> and
+ <scm|datum-expiration><index|datum-expiration> return the key, value and
+ expiration time respectively. It can be tested if an object is a datum
+ object with the predicate <scm|datum?><index|datum?>.
+
+ The length of <var|value> may be at most
+ <scm|%max-datum-value-length><index|%max-datum-value-length>. If this
+ bound is exceeded, an appropriate
<scm|&overly-large-datum><index|&overly-large-datum>
+ and <scm|&who> condition is raised.
</explain>
<\explain>
- <scm|(datum-\<gtr\>insertion <var|datum> #:desired-replication-level)>
+ <scm|(datum-\<gtr\>insertion <var|datum>
+ #:desired-replication-level)><index|datum-\<gtr\>insertion>
<|explain>
Make an insertion object for inserting the datum <var|datum>, desiring a
replication level <var|desired-replication-level> (see
<reference|replication levels???>)<todo|various options>.
The datum and desired replication level can be recovered with the
- accessors <scm|insertion-\<gtr\>datum> and
- <var|insertion-desired-replication-level>. It can be tested if an object
- is an insertion object with the predicate <scm|insertion?>.
+ accessors <scm|insertion-\<gtr\>datum><index|insertion-\<gtr\>datum> and
+
<var|insertion-desired-replication-level><index|insertion-desired-replication-level>.
+ It can be tested if an object is an insertion object with the predicate
+ <scm|insertion?><index|insertion?>.
</explain>
<\explain>
- <scm|(make-query <var|type> <var|key> #:desired-replication-level)>
+ <scm|(make-query <var|type> <var|key>
+ #:desired-replication-level)><index|make-query>
<|explain>
Make a query object for searching for a value of block type <var|type>
(or its corresponding numeric value), with key <var|key> (a readable
@@ -1130,48 +1163,55 @@
<todo|various options, xquery>
The numeric value of the block type, the key and the desired replication
- level can be recovered with the accessors <scm|query-type>,
- <scm|query-key> and <scm|query-desired-replication-level>. It can be
- tested if an object is a query object with the predicate <scm|query?>.
+ level can be recovered with the accessors
+ <scm|query-type><index|query-type>, <scm|query-key><index|query-key> and
+
<scm|query-desired-replication-level><index|query-desired-replication-level>.
+ It can be tested if an object is a query object with the predicate
+ <scm|query?><index|query?>.
</explain>
<\explain>
- <scm|(datum-\<gtr\>search-result <var|datum> #:get-path #:put-path)>
+ <scm|(datum-\<gtr\>search-result <var|datum> #:get-path
+ #:put-path)><index|datum-\<gtr\>search-result>
<|explain>
Make a search result object for the datum <var|datum>. The datum can be
- recovered with the accessor <scm|search-result-\<gtr\>datum>. It can be
- tested if an object is a search result with the predicate
- <scm|search-result?>. The optional arguments <var|get-path> and
- <var|put-path>, when not false, are bytevector slices consisting of a
- list of <scm|/dht:path-element>.
-
- The <var|get-path> , if any, is the path from the storage location to the
- current peer. Conversely, the <var|put-path>, if any, is a path from the
- peer that inserted the datum into the DHT to the storage location. The
- <var|get-path> and <var|put-path> can be accessed with
- <scm|search-result-get-path> and <scm|search-result-put-path>
+ recovered with the accessor
<scm|search-result-\<gtr\>datum><index|search-result-\<gtr\>datum>.
+ It can be tested if an object is a search result with the predicate
+ <scm|search-result?><index|search-result?>. The optional arguments
+ <var|get-path> and <var|put-path>, when not false, are bytevector slices
+ consisting of a list of
<scm|/dht:path-element><index|/dht:path-element><index|path
+ element>.
+
+ The <var|get-path><index|get path> , if any, is the path from the storage
+ location to the current peer. Conversely, the <var|put-path><index|put
+ path>, if any, is a path from the peer that inserted the datum into the
+ DHT to the storage location. The <var|get-path> and <var|put-path> can be
+ accessed with <scm|search-result-get-path><index|search-result-get-path>
+ and <scm|search-result-put-path><index|search-result-put-path>
respectively.
When the datum, get path and put path together are too large, a
- <scm|&overly-large-paths> condition is raised. When the bytevector slice
- length of <var|get-path> or <var|put-path> is not a multiple of the size
- of a path element, then a <scm|&malformed-path> condition is raised.
+ <scm|&overly-large-paths><index|&overly-large-paths> condition is raised.
+ When the bytevector slice length of <var|get-path> or <var|put-path> is
+ not a multiple of the size of a path element, then a
+ <scm|&malformed-path><index|&malformed-path> condition is raised.
</explain>
<section|Accessing data in the DHT>
To insert a datum into the DHT, the procedure <scm|put!> is used. To find
- data matching a query, the procedure <scm|start-get!> is used.
+ data matching a query, the procedure <scm|start-get!> is
+ used.<index|searching the DHT><index|inserting data into the DHT>
<\explain>
- <scm|(start-get! <var|server> <var|query> <var|found>)>
+ <scm|(start-get! <var|server> <var|query> <var|found>)><index|start-get!>
<|explain>
Search for data matching <var|query> in the DHT. When a datum is found,
call the unary procedure <var|found> on the search result. It is possible
to find multiple data matching a query. In that case, <var|found> is
called multiple times. Searching happens asynchronuously; to stop the
- search, a fresh <em|search object> for controlling the search is
- returned.
+ search, a fresh <em|search object><index|search object> for controlling
+ the search is returned.
The procedure <var|found> is run from the context of <var|server>. As
such, if <var|found> blocks, then all operations on <var|server> might
@@ -1185,7 +1225,7 @@
</explain>
<\explain>
- <scm|(put! <var|server> <var|insertion> <var|#:confirmed>)>
+ <scm|(put! <var|server> <var|insertion> <var|#:confirmed>)><index|put!>
<|explain>
Perform the insertion <var|insertion>. When the datum has been inserted,
the optional thunk <var|confirmed> is called. A <em|put object> is
@@ -1195,12 +1235,12 @@
</explain>
<\explain>
- <scm|(copy-datum <var|old>)>
+ <scm|(copy-datum <var|old>)><index|copy-datum>
</explain|Make a copy of the datum <var|old>, such that modifications to
the slices in <var|old> do not impact the new datum.>
<\explain>
- <scm|(copy-search-result <var|old>)>
+ <scm|(copy-search-result <var|old>)><index|copy-search-result>
</explain|Make a copy of the search result <var|old>, such that
modification to the slices in <var|old> do not impact the new search
result.>
@@ -1214,13 +1254,13 @@
The DHT client and service communicate by sending <em|messages>. Usually,
only the implementation of the client and service need to construct and
analyse these messages, but nothing prevents other uses of the procedures
- in <scm|(gnu gnunet dht network)>, e.g. for learning, in a tool like
- Wireshark or for tests.
+ in <scm|(gnu gnunet dht network)><index|(gnu gnunet dht network)>, e.g. for
+ learning, in a tool like Wireshark or for tests.
- The <em|analysis> procedures assume that the message is well-formed and
- avoid constructing new bytevector slices by taking subslices. The
- <em|construction> procedures create fresh well-formed read-write bytevector
- slices.
+ The <em|analysis> procedures<index|analysis procedures> assume that the
+ message is well-formed and avoid constructing new bytevector slices by
+ taking subslices. The <em|construction> procedures<index|construction
+ procedures> create fresh well-formed read-write bytevector slices.
<\warning>
Possibly the type of <var|options> will change and possibly the options
@@ -1229,48 +1269,53 @@
<\explain>
<scm|(construct-client-get <var|query> <var|unique-id> #:optional
- (<var|options> 0))>
+ (<var|options> 0))><index|construct-client-get>
<|explain>
- Create a new <scm|/:msg:dht:client:get> message for the query object
- <var|query>, with <var|unique-id> as \<#2018\>unique id\<#2019\> and
- <var|options> as options.
+ Create a new <scm|/:msg:dht:client:get><index|/:msg:dht:client:get>
+ message for the query object <var|query>, with <var|unique-id> as
+ \<#2018\>unique id\<#2019\> and <var|options> as options.
</explain>
<\explain>
- <scm|(construct-client-put <var|insertion> #:optional (options 0))>
+ <scm|(construct-client-put <var|insertion> #:optional (options
+ 0))><index|construct-client-put>
<|explain>
- Create a new <scm|/:msg:dht:client:put> message for the insertion object
- <var|insertion> with <var|options> as options.
+ Create a new <scm|/:msg:dht:client:put><index|/:msg:dht:client:put>
+ message for the insertion object <var|insertion> with <var|options> as
+ options.
</explain>
<\explain>
- <scm|(construct-client-result <var|search-result> <var|unique-id>)>
+ <scm|(construct-client-result <var|search-result>
+ <var|unique-id>)><index|construct-client-result>
<|explain>
- Create a new <scm|/:msg:dht:client:result> message for the search result
- object <var|search-result>, with <var|unique-id> as \<#2018\>unique
- id\<#2019\> .
+ Create a new <scm|/:msg:dht:client:result><index|/:msg:dht:client:result>
+ message for the search result object <var|search-result>, with
+ <var|unique-id> as \<#2018\>unique id\<#2019\> .
</explain>
<\explain>
- <scm|(analyse-client-get <var|message>)>
+ <scm|(analyse-client-get <var|message>)><index|analyse-client-get>
<|explain>
Return the query object, the unique id and the options corresponding to
- the <scm|/:msg:dht:client:result> message <var|message>. Xqueries are
- currently unsupported.
+ the <scm|/:msg:dht:client:result><index|/:msg:dht:client:result> message
+ <var|message>. Xqueries are currently unsupported.
</explain>
<\explain>
- <scm|(analyse-client-put <var|message>)>
+ <scm|(analyse-client-put <var|message>)><index|analyse-client-put>
<|explain>
Return the insertion object and options corresponding to the
- <scm|/:msg:dht:client:put> message <var|message>.
+ <scm|/:msg:dht:client:put><index|/:msg:dht:client:put> message
+ <var|message>.
</explain>
<\explain>
- <scm|(analyse-client-result <var|message>)>
+ <scm|(analyse-client-result <var|message>)><index|analyse-client-result>
<|explain>
Return search result object and unique id for the
- <scm|/:msg:dht:client:result> message <var|message>.
+ <scm|/:msg:dht:client:result><index|/:msg:dht:client:result> message
+ <var|message>.
</explain>
<todo|monitoring messages>
@@ -1285,19 +1330,19 @@
<chapter|Cryptography>
- The module <scm|(gnu gnunet crypto)> has a few small wrappers around
- procedures from Guile-Gcrypt for performing cryptography on bytevector
- slices.
+ The module <scm|(gnu gnunet crypto)><index|(gnu gnunet crypto)> has a few
+ small wrappers around procedures from Guile-Gcrypt for performing
+ cryptography on bytevector slices.
<\explain>
- <scm|(hash/sha512! <var|slice> <var|to>)>
+ <scm|(hash/sha512! <var|slice> <var|to>)><index|hash/sha512!>
</explain|Compute the SHA-512 hash of <var|slice>, a readable bytevector
slice of arbitrary length, and write it to <var|to>, a writable bytevector
slice of length 512 bits / 64 bytes.<space|1em>The result is unspecified if
<var|slice> and <var|to> overlap.>
<\explain>
- <scm|(hash/sha512 <var|slice>)>
+ <scm|(hash/sha512 <var|slice>)><index|hash/sha512>
<|explain>
Like <scm|hash/sha512!>, but allocate the <var|>destination slice
<var|to> and return it.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.