This is an automated email from the ASF dual-hosted git repository.
szetszwo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-ratis.git
The following commit(s) were added to refs/heads/master by this push:
new b51ec88 RATIS-519. Improvements on README.md and
ratis-examples/README.md.
b51ec88 is described below
commit b51ec8850b8d340602e0a7f11bc73d1be5eef110
Author: Tsz Wo Nicholas Sze <[email protected]>
AuthorDate: Tue Apr 16 13:04:48 2019 +0800
RATIS-519. Improvements on README.md and ratis-examples/README.md.
---
README.md | 24 +++++++++++----
ratis-examples/README.md | 79 ++++++++++++++++++++++++++++++++++--------------
2 files changed, 75 insertions(+), 28 deletions(-)
diff --git a/README.md b/README.md
index d94f1a5..2db4baa 100644
--- a/README.md
+++ b/README.md
@@ -13,16 +13,28 @@
-->
# Apache Ratis
-Apache Ratis is a java library that implements the RAFT protocol [1].
-The Raft paper can be accessed at (https://raft.github.io/raft.pdf).
+*[Apache Ratis]* is a Java library that implements the Raft protocol [1],
+where an extended version of the Raft paper is available at
<https://raft.github.io/raft.pdf>.
The paper introduces Raft and states its motivations in following words:
- > Raft is a consensus algorithm for managing a replicated log. It produces a
result equivalent to (multi-)Paxos, and it is as efficient as Paxos, but its
structure is different from Paxos; this makes Raft more understandable than
Paxos and also provides a better foundation for building practical systems.
- Ratis aims to make raft available as a java library that can be used by any
system that needs to use a replicated log. It provides pluggability for state
machine implementations to manage replicated states. It also provides
pluggability for Raft log, and rpc implementations to make it easy for
integration with other projects. Another important goal is to support high
throughput data ingest so that it can be used for more general data replication
use cases.
+> Raft is a consensus algorithm for managing a replicated log.
+> It produces a result equivalent to (multi-)Paxos, and it is as efficient as
Paxos,
+> but its structure is different from Paxos; this makes Raft more
understandable than Paxos
+> and also provides a better foundation for building practical systems.
+
+Ratis aims to make Raft available as a java library that can be used by any
system that needs to use a replicated log.
+It provides pluggability for state machine implementations to manage
replicated states.
+It also provides pluggability for Raft log, and rpc implementations to make it
easy for integration with other projects.
+Another important goal is to support high throughput data ingest so that it
can be used for more general data replication use cases.
* To build the artifacts, see [BUILDING.md](BUILDING.md).
* To run the examples, see
[ratis-examples/README.md](ratis-examples/README.md).
-# Reference
-[1] _Diego Ongaro and John Ousterhout. 2014. In search of an understandable
consensus algorithm. In Proceedings of the 2014 USENIX conference on USENIX
Annual Technical Conference (USENIX ATC'14), Garth Gibson and Nickolai
Zeldovich (Eds.). USENIX Association, Berkeley, CA, USA, 305-320._
+## Reference
+1. Diego Ongaro and John Ousterhout,
+_[In Search of an Understandable Consensus Algorithm][Ongaro2014]_,
+2014 USENIX Annual Technical Conference (USENIX ATC 14) (Philadelphia, PA),
USENIX Association, 2014, pp. 305-319.
+
+[Ongaro2014]:
https://www.usenix.org/conference/atc14/technical-sessions/presentation/ongaro
+[Apache Ratis]: http://ratis.incubator.apache.org/
diff --git a/ratis-examples/README.md b/ratis-examples/README.md
index eadf040..ccabe0d 100644
--- a/ratis-examples/README.md
+++ b/ratis-examples/README.md
@@ -16,68 +16,103 @@
#### Building and Running The Examples
-Compile the repository using `mvn clean package -DskipTests` under the project
root directory;
+The repository can be complied using `mvn clean package -DskipTests` under the
project root directory;
see also [BUILDING.md](../BUILDING.md).
-All the scripts for running the examples are located in the
[ratis-examples/src/main/bin](src/main/bin) directory,
+All the scripts for running the examples are located in the
[ratis-examples/src/main/bin](src/main/bin) directory;
+see below for the usage.
## Example 1: FileStore
-**FileStore** is file service supporting *read*, *write* and *delete*
operations.
+**FileStore** is a high performance file service supporting *read*, *write*
and *delete* operations.
The **FileStoreStateMachine** is implemented using the asynchronous
event-driven model.
The source code is located in
*
[ratis-examples/src/main/java/org/apache/ratis/examples/filestore/](src/main/java/org/apache/ratis/examples/filestore).
-#### Server
-To spawn a *FileStore* server, run
+#### FileStore Server
+To spawn a FileStore server, run
* `server.sh filestore server --id <SELF_ID> --storage <STORAGE_DIR> --peers
<ID:IP_ADDRESS,...>`
-where `<SELF_ID>`, which must be in the peer list, is the id of the instance
being spawned.
+where
+* `<SELF_ID>`, which must be in the peer list, is the ID of the instance being
spawned,
+* `<STORAGE_DIR>` is a local directory for storing Raft log and other data, and
+* `<ID:IP_ADDRESS,...>`, which is a comma separated list of ID and IP address
pairs, specifies the list of server peers.
-For example `ratis-examples/src/main/bin/server.sh filestore server --id n0
--storage /tmp/data --peers
n0:xx.xx.xx.xx:6000,n1:yy.yy.yy.yy:6001,n2:zz.zz.zz.zz:6002`
+Note that when multiple servers running at the same host, they must use
different `<STORAGE_DIR>`.
-#### Client
+For example,
-To spawn a *FileStore* load generation client, run
+ BIN=ratis-examples/src/main/bin
+ PEERS=n0:127.0.0.1:6000,n1:127.0.0.1:6001,n2:127.0.0.1:6002
+
+ ID=n0; ${BIN}/server.sh filestore server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+ ID=n1; ${BIN}/server.sh filestore server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+ ID=n2; ${BIN}/server.sh filestore server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+
+#### FileStore Client
+
+To spawn a FileStore load generation client, run
* `client.sh filestore loadgen --size <FILE_SIZE> --numFiles <NUM_FILES>
--peers <ID:IP_ADDRESS,...>`
-where `<FILE_SIZE>` is the size of the files to be generated in bytes,
-`<NUM_FILES>` is the number of files to be generated.
+where
+* `<FILE_SIZE>` is the size of the files to be generated in bytes, and
+* `<NUM_FILES>` is the number of files to be generated.
+
+Continue the server command example,
-For example `ratis-examples/src/main/bin/client.sh filestore loadgen --size
1048576 --numFiles 1000 --peers
n0:xx.xx.xx.xx:6000,n1:yy.yy.yy.yy:6001,n2:zz.zz.zz.zz:6002`
+ ${BIN}/client.sh filestore loadgen --size 1048576 --numFiles 1000 --peers
${PEERS}
## Example 2: Arithmetic
**Arithmetic** is an implementation of a replicated state machine.
-A *variable map* is stored in the *ArithmeticStateMachine* which supports
*assign* or *get* operations.
+A *variable map* is stored in the **ArithmeticStateMachine** which supports
*assign* and *get* operations.
Clients may assign a variable to a value by specifying either the value or a
formula to compute the value.
In
[TestArithemetic](src/test/java/org/apache/ratis/examples/arithmetic/TestArithmetic.java),
-it uses Arithmetic to solve *Pythagorean* equation and compute π using
Gauss–Legendre algorithm.
+it uses Arithmetic to solve Pythagorean equation and compute π using
Gauss–Legendre algorithm.
The source code is located in
*
[ratis-examples/src/main/java/org/apache/ratis/examples/arithmetic/](src/main/java/org/apache/ratis/examples/arithmetic).
-#### Server
-To spawn an *Arithmetic* server, run
+#### Arithmetic Server
+To spawn an Arithmetic server, run
* `server.sh arithmetic server --id <SELF_ID> --storage <STORAGE_DIR> --peers
<ID:IP_ADDRESS,...>`
-where `<SELF_ID>`, which must be in the peer list, is the id of the instance
being spawned.
+where
+* `<SELF_ID>`, which must be in the peer list, is the ID of the instance being
spawned,
+* `<STORAGE_DIR>` is a local directory for storing Raft log and other data, and
+* `<ID:IP_ADDRESS,...>`, which is a comma separated list of ID and IP address
pairs, specifies the list of server peers.
-For example `ratis-examples/src/main/bin/server.sh arithmetic server --id n0
--storage /tmp/data --peers
n0:xx.xx.xx.xx:6000,n1:yy.yy.yy.yy:6001,n2:zz.zz.zz.zz:6002`
+Note that when multiple servers running at the same host, they must use
different `<STORAGE_DIR>`.
-#### Client
+For example,
-To run an *Arithmetic* client command, run
+ BIN=ratis-examples/src/main/bin
+ PEERS=n0:127.0.0.1:6000,n1:127.0.0.1:6001,n2:127.0.0.1:6002
+
+ ID=n0; ${BIN}/server.sh arithmetic server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+ ID=n1; ${BIN}/server.sh arithmetic server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+ ID=n2; ${BIN}/server.sh arithmetic server --id ${ID} --storage
/tmp/ratis/${ID} --peers ${PEERS}
+
+#### Arithmetic Client
+
+To run an Arithmetic client command, run
* `client.sh arithmetic get --name <VAR> --peers <ID:IP_ADDRESS,...>`
or
* `client.sh arithmetic assign --name <VAR> --value <VALUE> --peers
<ID:IP_ADDRESS,...>`
-where `<VAR>` is the name of the variable and `<VALUE>` is the value to be
assigned.
+where
+* `<VAR>` is the name of a variable, and
+* `<VALUE>` is the value (or a formula to compute the value) to be assigned.
+
+Continue the server command example,
-For example `ratis-examples/src/main/bin/client.sh arithmetic get --name b
--peers n0:xx.xx.xx.xx:6000,n1:yy.yy.yy.yy:6001,n2:zz.zz.zz.zz:6002`
+ ${BIN}/client.sh arithmetic assign --name a --value 3 --peers ${PEERS}
+ ${BIN}/client.sh arithmetic assign --name b --value 4 --peers ${PEERS}
+ ${BIN}/client.sh arithmetic assign --name c --value a+b --peers ${PEERS}
+ ${BIN}/client.sh arithmetic get --name c --peers ${PEERS}
## Pre-Setup Vagrant Pseudo Cluster
One can see the interactions of a three server Ratis cluster with a
load-generator running against it
