github.com/jincm/wesharechain@v0.0.0-20210122032815-1537409ce26a/chain/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