[fluo-website] branch gh-pages updated: Added read locks to tour (#156)

[kt...@apache.org]

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

kturner pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/fluo-website.git


The following commit(s) were added to refs/heads/gh-pages by this push:
     new 8590b7a  Added read locks to tour (#156)
8590b7a is described below

commit 8590b7a9d574e39303ce9d8daf1986b3d295b81a
Author: Keith Turner <ke...@deenlo.com>
AuthorDate: Wed Mar 28 10:29:54 2018 -0400

    Added read locks to tour (#156)
---
 _data/tour.yml         |  2 ++
 tour/read-lock-code.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++
 tour/read-lock.md      | 30 ++++++++++++++++++++++
 tour/write-skew.md     |  3 ++-
 4 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/_data/tour.yml b/_data/tour.yml
index 1f22c44..1b26bf7 100644
--- a/_data/tour.yml
+++ b/_data/tour.yml
@@ -11,6 +11,8 @@ docs:
  - tx-logging
  - write-skew
  - write-skew-code
+ - read-lock
+ - read-lock-code
  - scanning
  - scanning-code
  - multi-get
diff --git a/tour/read-lock-code.md b/tour/read-lock-code.md
new file mode 100644
index 0000000..4b64e6f
--- /dev/null
+++ b/tour/read-lock-code.md
@@ -0,0 +1,67 @@
+---
+title: Read Lock Code
+---
+
+```java
+  private static final Column WEIGHT_COL = new Column("stat", "weight");
+
+  private static void exercise(MiniFluo mini, FluoClient client) {
+    try (Transaction tx1 = client.newTransaction()) {
+      tx1.set("kerbalnaut0001", WEIGHT_COL, "90");
+      tx1.set("kerbalnaut0002", WEIGHT_COL, "70");
+      tx1.set("kerbalnaut0003", WEIGHT_COL, "80");
+      tx1.commit();
+    }
+
+    try (Transaction tx2 = client.newTransaction();
+         Transaction tx3 = client.newTransaction();
+         Transaction tx4 = client.newTransaction())
+    {
+      int f1w1 = Integer.parseInt(tx2.withReadLock().gets("kerbalnaut0001", WEIGHT_COL));
+      int f1w2 = Integer.parseInt(tx2.withReadLock().gets("kerbalnaut0003", WEIGHT_COL));
+      tx2.set("flight0001", WEIGHT_COL, f1w1 + f1w2 + "");
+
+      int f2w1 = Integer.parseInt(tx3.withReadLock().gets("kerbalnaut0001", WEIGHT_COL));
+      int f2w2 = Integer.parseInt(tx3.withReadLock().gets("kerbalnaut0002", WEIGHT_COL));
+      tx3.set("flight0002", WEIGHT_COL, f2w1 + f2w2 + "");
+
+      tx4.set("kerbalnaut0001", WEIGHT_COL, "95");
+
+      for(Transaction ctx : Arrays.asList(tx2,tx3,tx4)) {
+        try {
+         ctx.commit();
+        } catch (CommitException ce) {
+          System.out.println("commit failed: "+ce.getMessage());
+        }
+      }
+    }
+
+    try(Snapshot snap = client.newSnapshot()) {
+      snap.scanner().build().forEach(System.out::println);
+    }
+  }
+```
+
+Output :
+
+```
+commit failed: Collisions(1):kerbalnaut0001 stat weight
+flight0001 stat weight  170
+flight0002 stat weight  160
+kerbalnaut0001 stat weight  90
+kerbalnaut0002 stat weight  70
+kerbalnaut0003 stat weight  80
+```
+
+Output for commit order `Arrays.asList(tx4,tx2,tx3)` :
+
+```
+commit failed: Collisions(1):kerbalnaut0001 stat weight
+commit failed: Collisions(1):kerbalnaut0001 stat weight
+kerbalnaut0001 stat weight  95
+kerbalnaut0002 stat weight  70
+kerbalnaut0003 stat weight  80
+```
+
+With this commit order *tx4* gets a write lock on *kerbalnaut0001:stat:weight*
+which prevents *tx2* and *tx3* from getting read locks.
diff --git a/tour/read-lock.md b/tour/read-lock.md
new file mode 100644
index 0000000..6e3c524
--- /dev/null
+++ b/tour/read-lock.md
@@ -0,0 +1,30 @@
+---
+title: Read Locks
+---
+
+By default, reads do not acquire a lock which makes normal reads faster.
+Read locks can optionally be acquired via the [withReadLock] method. For
+example, if `tx` is a transaction then `tx.withReadLock().get(row,col)`
+reads with a lock.
+
+
+ * **Create transaction** *tx1*
+ * **Using** *tx1* **set** *kerbalnaut0001:stat:weight* **to** *90*
+ * **Using** *tx1* **set** *kerbalnaut0002:stat:weight* **to** *70*
+ * **Using** *tx1* **set** *kerbalnaut0003:stat:weight* **to** *80*
+ * **Commit** *tx1*
+ * **Create transaction** *tx2*
+ * **Create transaction** *tx3*
+ * **Create transaction** *tx4*
+ * **Using** *tx2* **set** *flight0001:stat:weight* **to the read locked values of** *kerbalnaut0001:stat:weight* **plus** *kerbalnaut0003:stat:weight*
+ * **Using** *tx3* **set** *flight0002:stat:weight* **to the read locked values of** *kerbalnaut0001:stat:weight* **plus** *kerbalnaut0002:stat:weight*
+ * **Using** *tx4* **set** *kerbalnaut0001:stat:weight* **to** *95*
+ * **Commit** *tx2*
+ * **Commit** *tx3*
+ * **Commit** *tx4*
+
+Both *tx2* and *tx3* get a read lock on *kerbalnaut0001:stat:weight* without
+interfering with each other.  The read locks prevent *tx4* from committing.
+Try reordering the commits for *tx2*, *tx3*, and *tx4*.
+
+[withReadLock]: {{ site.fluo_api_static }}/{{ site.latest_fluo_release }}/org/apache/fluo/api/client/TransactionBase.html#withReadLock--
diff --git a/tour/write-skew.md b/tour/write-skew.md
index 7e457f4..ce5c0cf 100644
--- a/tour/write-skew.md
+++ b/tour/write-skew.md
@@ -27,4 +27,5 @@ different keys.
 The changes made by *tx3* will not be seen by *tx2*. This behavior is OK if the update made by *tx3*
 triggers a later update of *n0:data:sum*. Later pages in the tour will show that Observers can work
 this way, so that eventually the changes made by *tx3* are incorporated.  The [Weak Notification
-Exercise](/tour/weak-notifications/) later in the tour shows an example of this.
+Exercise](/tour/weak-notifications/) later in the tour shows an example of this. Another strategy
+for dealing with write skew is [read locks](/tour/read-lock/).

-- 
To stop receiving notification emails like this one, please contact
kturner@apache.org.