update readme

README.md

@@ -1,2 +1,121 @@
 # swim-js [![Build Status](https://travis-ci.org/mrhooray/swim-js.svg?branch=master)](https://travis-ci.org/mrhooray/swim-js)
 > JavaScript implementation of [Gossip](http://en.wikipedia.org/wiki/Gossip_protocol) protocol based on [SWIM](http://www.cs.cornell.edu/~asdas/research/dsn02-SWIM.pdf)
+
+* [Motivation](#motivation)
+* [Usage](#usage)
+* [Benchmark](#benchmark)
+* [TODO](#todo)
+* [License](#license)
+
+##Motivation
+A decentralized way of managing membership is needed for large clusters.
+Swim handles failure detection and membership dissemination in a scalable and weakly-consistent way.
+It can be used in implementation of consistent hash ring, application layer sharding and replication, etc.
+
+##Usage
+Installation
+```sh
+npm install swim --save
+```
+```js
+var Swim = require('swim');
+var opts = {
+    local: {
+        host: '10.31.1.191:11000',
+        meta: {'application': 'info'} // optional
+    },
+    codec: 'msgpack', // optional
+    disseminationFactor: 15, // optional
+    interval: 100, // optional
+    joinTimeout: 200, // optional
+    pingTimeout: 20, // optional
+    pingReqTimeout: 60, // optional
+    pingReqGroupSize: 3, // optional
+    udp: {maxDgramSize: 512} // optional
+};
+var swim = new Swim(opts);
+var hostsToJoin = ['10.31.1.192:11000', '10.31.1.193:11000'];
+
+swim.bootstrap(hostsToJoin, function onBootstrap(err) {
+    if (err) {
+        // error handling
+        return;
+    }
+
+    // ready
+    console.log(swim.whoami());
+    console.log(swim.members());
+    console.log(swim.checksum());
+
+    // change on membership, e.g. new node or node died/left
+    swim.on(Swim.EventType.Change, function onChange(update) {});
+    // update on membership, e.g. node recovered or update on meta data
+    swim.on(Swim.EventType.Update, function onUpdate(update) {});
+
+    // shutdown
+    swim.leave();
+});
+
+// or
+swim.bootstrap(hostsToJoin);
+// bootstrap error handling
+swim.on(Swim.EventType.Error, function onError(err) {});
+// bootstrap ready
+swim.on(Swim.EventType.Ready, function onReady() {});
+```
+
+##Benchmark
+Benchmark convergence time under different configuration
+```sh
+node bench/script/convergence-time.js -h
+
+  Usage: convergence-time [options]
+
+  Options:
+
+    -h, --help                      output usage information
+    --cycles [value]                number of cycles
+    --workers [value]               number of workers
+    --codec [value]                 msgpack or json
+    --dissemination-factor [value]  dissemination factor
+    --interval [value]              interval
+    --join-timeout [value]          join timeout
+    --ping-timeout [value]          ping timeout
+    --ping-req-timeout [value]      ping req timeout
+    --ping-req-group-size [value]   ping req group size
+    --max-dgram-size [value]        max dgram size
+```
+```sh
+node bench/script/convergence-time.js
+
+configuration:
+- cycles 10
+- workers 10
+- codec msgpack
+- dissemination factor 15
+- interval 20 ms
+- join timeout 100 ms
+- ping timeout 4 ms
+- ping req timeout 12 ms
+- ping req group size 3
+- max dgram size 512 bytes
+convergence time under single node failure
+histogram data:
+- count 10
+- min 76
+- max 123
+- mean 100
+- median 101
+- variance 308.44444444444446
+- std dev 17.56258649642599
+- p75 116.25
+- p95 123
+- p99 123
+```
+
+##TODO
+- [ ] Documentation for API and events
+- [ ] Optional secondary protocol like periodic full sync
+
+##License
+MIT