From aa93e475a481feeb5cc0e673d0bdf360b27fb368 Mon Sep 17 00:00:00 2001 From: Mark Qvist Date: Mon, 17 May 2021 15:57:41 +0200 Subject: [PATCH] Updated docs --- RNS/Resource.py | 26 +++++++++++------------ docs/source/understanding.rst | 40 +++++++++-------------------------- 2 files changed, 22 insertions(+), 44 deletions(-) diff --git a/RNS/Resource.py b/RNS/Resource.py index 99840ec..3a44a21 100644 --- a/RNS/Resource.py +++ b/RNS/Resource.py @@ -31,22 +31,20 @@ class Resource: SDU = RNS.Packet.MDU RANDOM_HASH_SIZE = 4 - MAX_EFFICIENT_SIZE = 16 * 1024 * 1024 - """ - This is an indication of what the - maximum size a resource should be, if - it is to be handled within reasonable - time constraint, even on small systems. + # This is an indication of what the + # maximum size a resource should be, if + # it is to be handled within reasonable + # time constraint, even on small systems. - A small system in this regard is - defined as a Raspberry Pi, which should - be able to compress, encrypt and hash-map - the resource in about 10 seconds. - - This constant will be used when determining - how to sequence the sending of large resources. - """ + # A small system in this regard is + # defined as a Raspberry Pi, which should + # be able to compress, encrypt and hash-map + # the resource in about 10 seconds. + # This constant will be used when determining + # how to sequence the sending of large resources. + MAX_EFFICIENT_SIZE = 16 * 1024 * 1024 + # The maximum size to auto-compress with # bz2 before sending. AUTO_COMPRESS_MAX_SIZE = MAX_EFFICIENT_SIZE diff --git a/docs/source/understanding.rst b/docs/source/understanding.rst index 69ba63b..5b87f32 100644 --- a/docs/source/understanding.rst +++ b/docs/source/understanding.rst @@ -449,38 +449,18 @@ automate retransmissions if *Resources* are used. Resources --------- -TODO: Write +For exchanging small amounts of data over a Reticulum network, the :ref:`Packet` interface +is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate +the transfer is needed. -In traditional networks, large amounts of data is rapidly exchanged with very low latency. Links of -several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and -as such, traditional protocols are often designed to not store any transmitted data at intermediary -hops. If a transmission error occurs, the sending node will simply notice the lack of a packet -acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it -got the intended data. +This is the purpose of the Reticulum :ref:`Resource`. A *Resource* can automatically +handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link`. +Resources can auto-compress data, will handle breaking the data into individual packets, sequencing +the transfer and reassembling the data on the other end. -In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the -network, and communications that span many hops become exceedingly expensive in terms of -bandwidth usage, due to the higher risk of some packets failing. - -Reticulum alleviates this in part with it’s *path* discovery methodology, and in part by implementing -*resource* caching at all nodes that can support it. Network operation can be made much more -efficient by caching everything for a period of time, and given the availability of cheap memory and -storage, this is a very welcome tradeoff. A gigabyte of memory can store millions of Reticulum -packets, and since everything is encrypted by default, the storing poses very little privacy risk. - -In a Reticulum network, any node that is able to do so, should cache as many packets as it’s -memory will allow for. When a packet is received, a timestamp and a hash of the packet is stored -along with the full packet itself, and it will be kept in storage until the allocated cache storage is -full, whereupon the packet that was last accessed in the cache will be deleted. If a packet is accessed -from the cache, it’s timestamp will be updated to the current time, to ensure that packets that are -used stay in the cache, and packets that are not used are dropped from memory. - -Some packet types are stored in separate caching tables, that allow easier lookup for other nodes. -For example, an announce is stored in a way, that allows other nodes to request the public key for a -certain destination, and as such the network as a whole operates as a distributed key ledger. - -For more details on how the caching works and is used, see the reference implementation source -code. +:ref:`Resources` are programmatically very simple to use, and only requires a few lines +of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory, +or stream data directly from files. .. _understanding-referencesystem: