You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@curator.apache.org by ra...@apache.org on 2014/03/07 14:43:18 UTC
[1/2] git commit: Added doc
Repository: curator
Updated Branches:
refs/heads/CURATOR-88 05d5420f1 -> fbd9c39ca
Added doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/248bb2a8
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/248bb2a8
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/248bb2a8
Branch: refs/heads/CURATOR-88
Commit: 248bb2a8b0088c9d831c912250fa6aba733bbc2c
Parents: 05d5420
Author: randgalt <ra...@apache.org>
Authored: Fri Mar 7 08:35:47 2014 -0500
Committer: randgalt <ra...@apache.org>
Committed: Fri Mar 7 08:35:47 2014 -0500
----------------------------------------------------------------------
.../locks/InterProcessSemaphoreReadWrite.java | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/248bb2a8/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
index 26912c0..e1118db 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
@@ -29,6 +29,24 @@ import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicReference;
+/**
+ * <p>
+ * A NON re-entrant read-write lock that works across JVMs. Uses Zookeeper to hold
+ * the lock. All processes in all JVMs that use the same lock path will achieve an
+ * inter-process critical section. Further, this mutex is "fair" - each user will
+ * get the mutex in the order requested (from ZK's point of view).
+ * </p>
+ *
+ * <p>
+ * A read write lock maintains a pair of associated locks, one for read-only operations and one
+ * for writing. The read lock may be held simultaneously by multiple reader processes, so long as
+ * there are no writers. The write lock is exclusive.
+ * </p>
+ *
+ * <p>
+ * Note: lock upgrading/downgrading is NOT supported by this implementation.
+ * </p>
+ */
public class InterProcessSemaphoreReadWrite implements InterProcessReadWriteLockBase
{
private final InterProcessSemaphoreV2 lock;
[2/2] git commit: doc
Posted by ra...@apache.org.
doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/fbd9c39c
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/fbd9c39c
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/fbd9c39c
Branch: refs/heads/CURATOR-88
Commit: fbd9c39ca9ed7be5bfb6ef35a80f586e003139a4
Parents: 248bb2a
Author: randgalt <ra...@apache.org>
Authored: Fri Mar 7 08:40:28 2014 -0500
Committer: randgalt <ra...@apache.org>
Committed: Fri Mar 7 08:40:28 2014 -0500
----------------------------------------------------------------------
.../locks/InterProcessSemaphoreReadWrite.java | 4 ++
.../src/site/confluence/index.confluence | 1 +
.../shared-read-write-lock.confluence | 39 ++++++++++++++++++++
3 files changed, 44 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/fbd9c39c/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
index e1118db..be8f178 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/locks/InterProcessSemaphoreReadWrite.java
@@ -145,6 +145,10 @@ public class InterProcessSemaphoreReadWrite implements InterProcessReadWriteLock
private static final String READ_BASE_NAME = "read" + SUFFIX;
private static final String WRITE_BASE_NAME = "write" + SUFFIX;
+ /**
+ * @param client the client
+ * @param path path to use for locking
+ */
public InterProcessSemaphoreReadWrite(CuratorFramework client, String path)
{
lock = new InterProcessSemaphoreV2(client, path, Integer.MAX_VALUE);
http://git-wip-us.apache.org/repos/asf/curator/blob/fbd9c39c/curator-recipes/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/index.confluence b/curator-recipes/src/site/confluence/index.confluence
index c37b0de..0ad104f 100644
--- a/curator-recipes/src/site/confluence/index.confluence
+++ b/curator-recipes/src/site/confluence/index.confluence
@@ -10,6 +10,7 @@ Curator implements all of the recipes listed on the ZooKeeper recipes doc (excep
|[[Shared Reentrant Lock|shared-reentrant-lock.html]] - Fully distributed locks that are globally synchronous, meaning at any snapshot in time no two clients think they hold the same lock.|
|[[Shared Lock|shared-lock.html]] - Similar to Shared Reentrant Lock but not reentrant.|
|[[Shared Reentrant Read Write Lock|shared-reentrant-read-write-lock.html]] - A re-entrant read/write mutex that works across JVMs. A read write lock maintains a pair of associated locks, one for read-only operations and one for writing. The read lock may be held simultaneously by multiple reader processes, so long as there are no writers. The write lock is exclusive.|
+|[[Shared Read Write Lock|shared-read-write-lock.html]] - Similar to Reentrant Read Write Lock but is not re-entrant and does not support upgrading/downgrading.|
|[[Shared Semaphore|shared-semaphore.html]] - A counting semaphore that works across JVMs. All processes in all JVMs that use the same lock path will achieve an inter-process limited set of leases. Further, this semaphore is mostly "fair" - each user will get a lease in the order requested (from ZK's point of view).|
|[[Multi Shared Lock|multi-shared-lock.html]] - A container that manages multiple locks as a single entity. When acquire() is called, all the locks are acquired. If that fails, any paths that were acquired are released. Similarly, when release() is called, all locks are released (failures are ignored).|
http://git-wip-us.apache.org/repos/asf/curator/blob/fbd9c39c/curator-recipes/src/site/confluence/shared-read-write-lock.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-read-write-lock.confluence b/curator-recipes/src/site/confluence/shared-read-write-lock.confluence
new file mode 100644
index 0000000..86b6ee2
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-read-write-lock.confluence
@@ -0,0 +1,39 @@
+h1. Shared Reentrant Read Write Lock
+
+h2. Description
+A NON re-entrant read/write mutex that works across JVMs. Uses Zookeeper to hold the lock. All processes in all
+JVMs that use the same lock path will achieve an inter-process critical section. Further, this mutex is "fair" -
+each user will get the mutex in the order requested (from ZK's point of view).
+
+A read write lock maintains a pair of associated locks, one for read-only operations and one for writing. The read
+lock may be held simultaneously by multiple reader processes, so long as there are no writers. The write lock is exclusive.
+
+Lock upgrading/downgrading is NOT supported by this implementation.
+
+h2. Participating Classes
+* InterProcessSemaphoreReadWrite
+* InterProcessLock
+
+h2. Usage
+h3. Create an InterProcessReadWriteLock
+{code}
+public InterProcessSemaphoreReadWrite(CuratorFramework client,
+ String basePath)
+Parameters:
+client - the client
+basePath - path to use for locking
+{code}
+
+h3. General Usage
+Access either the read lock or the write lock and then use the methods as described for [[Shared lock|shared-lock.html]].
+
+{code}
+public InterProcessLock readLock()
+
+public InterProcessLock writeLock()
+{code}
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and
+LOST state changes. If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you
+subsequently receive a RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.