[zookeeper] branch master updated: ZOOKEEPER-3522: Reword Zookeeper consistency doc for clarity

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hanm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/zookeeper.git


The following commit(s) were added to refs/heads/master by this push:
     new 614224e  ZOOKEEPER-3522: Reword Zookeeper consistency doc for clarity
614224e is described below

commit 614224e318551a4ba332618cbd377050f19e1f3f
Author: Srikanth Viswanathan <sr...@gmail.com>
AuthorDate: Thu Sep 5 14:48:15 2019 -0700

    ZOOKEEPER-3522: Reword Zookeeper consistency doc for clarity
    
    Noticed a few opportunities to rewrite the zookeeper consistency section for clarity
    
    Author: Srikanth Viswanathan <sr...@gmail.com>
    
    Reviewers: Michael Han <ha...@apache.org>
    
    Closes #1076 from srikanth-viswanathan/patch-1
---
 .../src/main/resources/markdown/zookeeperInternals.md     | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md b/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md
index 25d9be8..0505807 100644
--- a/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md
+++ b/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md
@@ -271,20 +271,13 @@ proposals and to not worry about duplicate proposals for a given zxid.
 
 ## Consistency Guarantees
 
-ZooKeeper [consistency](https://jepsen.io/consistency) guarantees lie between sequential consistency and linearizabiliy. Here, we explain the exact consistency guarantees that ZooKepeer provides.
+The [consistency](https://jepsen.io/consistency) guarantees of ZooKeeper lie between sequential consistency and linearizability. In this section, we explain the exact consistency guarantees that ZooKeeper provides.
 
-Write operations in ZooKeeper are linearizabile. In other words, each write appears to take effect atomically at some point between its invocation and its response. This means that the writes performed by all the clients in ZooKeeper can be totally ordered in such a way that respects the real-time ordering of these writes. However, note that just stating that writes are linearizable is meaningless unless we also talk about read operations.
+Write operations in ZooKeeper are *linearizable*. In other words, each `write` will appear to take effect atomically at some point between when the client issues the request and receives the corresponding response. This means that the writes performed by all the clients in ZooKeeper can be totally ordered in such a way that respects the real-time ordering of these writes. However, merely stating that write operations are linearizable is meaningless unless we also talk about read operations.
 
-Read operations in ZooKeeper are not linearizable since they can return potentially stale data. This occurs since a read in ZooKeeper is not a quorum operation and a server responds immediately to a client that is performing a read.
-Nevertheless, ZooKeeper makes this choice because it chooses performance in the trade-off between performance and consistency. ZooKeeper read operations are sequentially-consistent, since read operations appear to take effect in some sequential order that furthermore respects the order of each client's operations. 
-If a client wants to read the freshest data, it is generally assumed that the client should first perform a sync operation, and then a read.
-However, even with a sync before a read operation, a client might retrieve stale data.
-This can occur because `sync` is [not a quorum operation](https://issues.apache.org/jira/browse/ZOOKEEPER-1675). Such a scenario might appear if two servers think that they are the leaders at the same time, which may occur if the time it takes for a TCP connection to drop is smaller than `syncLimit * tickTime`, something that is [unlikely](https://www.amazon.com/ZooKeeper-Distributed-Coordination-Flavio-Junqueira/dp/1449361307) to occur in practice.
+Read operations in ZooKeeper are *not linearizable* since they can return potentially stale data. This is because a `read` in ZooKeeper is not a quorum operation and a server will respond immediately to a client that is performing a `read`. ZooKeeper does this because it prioritizes performance over consistency for the read use case. However, reads in ZooKeeper are *sequentially consistent*, because `read` operations will appear to take effect in some sequential order that furthermore re [...]
 
-
-This raises the question on what are the exact consistency guarantees of ZooKeeper?
-Formally, the ZooKeeper consistency guarantees are captured by the notion of [ordered sequential consistency](http://webee.technion.ac.il/people/idish/ftp/OSC-IPL17.pdf) or `OSC(U)` to be exact, that lies  between sequential consistency and linearizability.
-Finally, note that the current version of ZooKeeper can provide linearizability for both reads and writes, if every read is preceded by a write to some dummy znode. 
+Overall, the consistency guarantees of ZooKeeper are formally captured by the notion of [ordered sequential consistency](http://webee.technion.ac.il/people/idish/ftp/OSC-IPL17.pdf) or `OSC(U)` to be exact, which lies between sequential consistency and linearizability.
 
 <a name="sc_quorum"></a>