github.com/oskarth/go-ethereum@v1.6.8-0.20191013093314-dac24a9d3494/swarm/pot/doc.go (about)

     1  // Copyright 2017 The go-ethereum Authors
     2  // This file is part of the go-ethereum library.
     3  //
     4  // The go-ethereum library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-ethereum library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  /*
    18  Package pot (proximity order tree) implements a container similar to a binary tree.
    19  The elements are generic Val interface types.
    20  
    21  Each fork in the trie is itself a value. Values of the subtree contained under
    22  a node all share the same order when compared to other elements in the tree.
    23  
    24  Example of proximity order is the length of the common prefix over bitvectors.
    25  (which is equivalent to the reverse rank of order of magnitude of the MSB first X
    26  OR distance over finite set of integers).
    27  
    28  Methods take a comparison operator (pof, proximity order function) to compare two
    29  value types. The default pof assumes Val to be or project to a byte slice using
    30  the reverse rank on the MSB first XOR logarithmic distance.
    31  
    32  If the address space if limited, equality is defined as the maximum proximity order.
    33  
    34  The container offers applicative (functional) style methods on PO trees:
    35  * adding/removing en element
    36  * swap (value based add/remove)
    37  * merging two PO trees (union)
    38  
    39  as well as iterator accessors that respect proximity order
    40  
    41  When synchronicity of membership if not 100% requirement (e.g. used as a database
    42  of network connections), applicative structures have the advantage that nodes
    43  are immutable therefore manipulation does not need locking allowing for
    44  concurrent retrievals.
    45  For the use case where the entire container is supposed to allow changes by
    46  concurrent routines,
    47  
    48  Pot
    49  * retrieval, insertion and deletion by key involves log(n) pointer lookups
    50  * for any item retrieval  (defined as common prefix on the binary key)
    51  * provide synchronous iterators respecting proximity ordering  wrt any item
    52  * provide asynchronous iterator (for parallel execution of operations) over n items
    53  * allows cheap iteration over ranges
    54  * asymmetric concurrent merge (union)
    55  
    56  Note:
    57  * as is, union only makes sense for set representations since which of two values
    58  with equal keys survives is random
    59  * intersection is not implemented
    60  * simple get accessor is not implemented (but derivable from EachNeighbour)
    61  
    62  Pinned value on the node implies no need to copy keys of the item type.
    63  
    64  Note that
    65  * the same set of values allows for a large number of alternative
    66  POT representations.
    67  * values on the top are accessed faster than lower ones and the steps needed to
    68  retrieve items has a logarithmic distribution.
    69  
    70  As a consequence one can organise the tree so that items that need faster access
    71  are torwards the top. In particular for any subset where popularity has a power
    72  distriution that is independent of proximity order (content addressed storage of
    73  chunks), it is in principle possible to create a pot where the steps needed to
    74  access an item is inversely proportional to its popularity.
    75  Such organisation is not implemented as yet.
    76  
    77  TODO:
    78  * overwrite-style merge
    79  * intersection
    80  * access frequency based optimisations
    81  
    82  */
    83  package pot