keith-turner closed pull request #156: Added read locks to tour
URL: https://github.com/apache/fluo-website/pull/156
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
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/).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
