X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=README.txt;h=42f9a82d8ffc60f8d66e38576fd171b3cbdb9ca2;hb=afd9fc11f10f380a46153e525f53d8636f5b4f50;hp=b089ab951e951d3cce61541b0c8c8477c5aa64ec;hpb=4ebfe7454d9257924a24c1660e7d0b64f3bfb23d;p=quix0rs-apt-p2p.git

diff --git a/README.txt b/README.txt
index b089ab9..42f9a82 100644
--- a/README.txt
+++ b/README.txt
@@ -1,16 +1,79 @@
+[Note: I have no idea how up to date the code examples are -- icepick ]
+
+Khashmir is a distributed hash table that uses an XOR distance metric and a
+routing table similar to Kademlia [1].  Use Khashmir to build distributed
+applications.  Note that Khashmir currently isn't very attack resistant.
+
+  1 - http://kademlia.scs.cs.nyu.edu/
+  
+Khashmir is implemented in Python using the Twisted [2] asynchronous networking
+framework.  Network deliver is done using UDP.  PySQLite is used for each
+peer's backing store of keys and values.  The backing store is currently
+held in memory but it could easily be placed on disk.  Values expire after
+24 hours, by default.  Each peer stores multiple values for a key and
+currently returns all available values when requested.
+  
+  2 - http://twistedmatrix.com
+
+If you just want to watch it build a test network of peers, run "python
+khashmir.py <num peers>" This script will create the specified number of
+peers, give each one three random contacts, tell each one to find the
+closest nodes, then pick a random peer and have it find another random peer
+(ten times), then pick a random peer to insert a key/value and have three
+random peers try to find it (ten times.)
+
 quick example:
 
->>> import khashmir
->>> k = khashmir.test_one(4444)  # choose any port
+>>> k = khashmir.test_one('<ip>', 4444)  # choose any port
+
+- which is the same thing as - 
+
+>>> import thread, khashmir
+>>> k = khashmir.Khashmir('<ip>', <port>) # choose any port
+>>> thread.start_new_thread(k.app.run, ())
+
+
+If you want to make another peer in the same session, use 
+
+>>> peer = khashmir.Khashmir(host, port) 
+
+then do 
 
-If you want to make another peer in the same session, use peer = khashmir.Khashmir(host, port) then do peer.app.run() to register with the already running thread.
+>>> peer.app.run() 
 
+to register with the already running thread.
+
+
+Now you need some contacts.  Add as some contacts and try to find close
+nodes in the network.
 
 >>> k.addContact('127.0.0.1', 8080)  # locate another peer
 >>> k.findCloseNodes()  # query the network to bootstrap our table
 
-Keys are always 20-character strings (sha1 hashes)
+Keys are always 20-character strings (sha1 hashes) currently there is no
+limit to value sizes, something will go in ASAP
+
+Now try storing and retrieving values.
 
->>> k.storeValueForKey(key, value)  # no callback right now
+# callback returns node info dictionaries and actual connection information
+# for peers that accepted the value. Currently finds the K closest nodes and
+# makes one attempt to store them
+>>> k.storeValueForKey(key, value, callback=None)  
+
+# callback returns lists of values, will fire multiple times, last time will
+# be an empty list
 >>> k.valueForKey(key, callback)
 
+
+
+TWEAKABLE SETTINGS:
+
+ktable.py: 
+	K - the size of routing table buckets, how many nodes to return
+	    in response to find-node/value request, and how many nodes to issue
+	    storeValue to; default is 8, which should work for hundreds of
+	    nodes, you might want to bump it if you think your network is going
+	    to be large
+
+A bunch of other tweakables are in const.py
+