Browse files

updated javadoc

  • Loading branch information...
1 parent f063a2d commit c69d63e8f71f7f06374c88fc59293a54caaeaa62 @belaban committed Jan 20, 2011
View
22 src/org/jgroups/blocks/locking/LockService.java
@@ -2,15 +2,37 @@
import org.jgroups.Event;
import org.jgroups.JChannel;
+import org.jgroups.annotations.Experimental;
import org.jgroups.protocols.Locking;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Condition;
import java.util.concurrent.locks.Lock;
/**
+ * LockService is the main class for to use for distributed locking functionality. LockService needs access to a
+ * {@link JChannel} and interacts with a locking protocol (e.g. {@link org.jgroups.protocols.CENTRAL_LOCK}) via events.<p/>
+ * When no locking protocol is seen on the channel's stack, LockService will throw an exception at startup. An example
+ * of using LockService is:
+ * <pre>
+ JChannel ch=new JChannel("/home/bela/locking.xml); // locking.xml needs to have a locking protocol towards the top
+ LockService lock_service=new LockService(ch);
+ ch.connect("lock-cluster");
+ Lock lock=lock_service.getLock("mylock");
+ lock.lock();
+ try {
+ // do something with the lock acquired
+ }
+ finally {
+ lock.unlock();
+ }
+ * </pre>
+ * Note that, contrary to the semantics of {@link java.util.concurrent.locks.Lock}, unlock() can be called multiple
+ * times; after a lock has been released, future calls to unlock() have no effect.
* @author Bela Ban
+ * @since 2.12
*/
+@Experimental
public class LockService {
protected JChannel ch;
protected Locking lock_prot;
View
19 src/org/jgroups/protocols/CENTRAL_LOCK.java
@@ -16,10 +16,23 @@
/**
- * Implementation of a lock service which acquires locks by contacting the coordinator.</p> Because the central
- * coordinator maintains all locks, no total order configuration is required.
- * An alternative is also the {@link org.jgroups.blocks.locking.PeerLockService}.
+ * Implementation of a locking protocol which acquires locks by contacting the coordinator.</p> Because the
+ * coordinator maintains all locks, no total order configuration is required.<p>
+ * CENTRAL_LOCK has all members send lock and unlock requests to a central coordinator. The coordinator has a queue for
+ * incoming requests, and grants locks based on order of arrival. To prevent all acquired locks from being forgotten
+ * when the coordinator crashes, setting num_backups lets the coordinator backup lock information to a number of
+ * backup nodes. Valid values for num_backups are 0 (no backup) to N-1, e.g. in a cluster of 4, we can have only 3 backup
+ * nodes.</p>
+ * Say we have a cluster of {A,B,C,D,E} and num_backups=1. A is the coordinator, and A updates all locks (and released
+ * locks) in B as well. When A crashes, everybody falls over to B for sending lock and unlock requests.
+ * B in turn copies all existing locks over to C and - when locks are acquired or released - forwards this
+ * information to C as well.
+ * <p/>
+ * An alternative is also the {@link org.jgroups.protocols.PEER_LOCK} protocol.
* @author Bela Ban
+ * @since 2.12
+ * @see Locking
+ * @see PEER_LOCK
*/
@Experimental
public class CENTRAL_LOCK extends Locking implements LockNotification {
View
9 src/org/jgroups/protocols/Locking.java
@@ -22,7 +22,13 @@
/**
+ * Base locking protocol, handling most of the protocol communication with other instances. To use distributed locking,
+ * {@link org.jgroups.blocks.locking.LockService} is placed on a channel. LockService talks to a subclass of Locking
+ * via events.
* @author Bela Ban
+ * @since 2.12
+ * @see org.jgroups.protocols.CENTRAL_LOCK
+ * @see org.jgroups.protocols.PEER_LOCK
*/
abstract public class Locking extends Protocol {
@@ -164,8 +170,6 @@ public Object up(Event evt) {
log.error("Request of type " + req.type + " not known");
break;
}
-
-
return null;
case Event.VIEW_CHANGE:
@@ -192,7 +196,6 @@ public void unlockAll() {
locks.addAll(map.values());
}
}
-
for(ClientLock lock: locks)
lock.unlock();
}
View
15 src/org/jgroups/protocols/PEER_LOCK.java
@@ -14,9 +14,9 @@
import java.util.Map;
/**
- * Implementation of a lock service which acquires locks by contacting all of the nodes of a cluster.</p> Unless a total
- * order configuration is used (e.g. {@link org.jgroups.protocols.SEQUENCER} based), lock requests for the same resource
- * from different senders may be received in different order, so deadlocks can occur. Example:
+ * Implementation of a locking protocol which acquires locks by contacting <em>all</em> of the nodes of a cluster.</p>
+ * Unless a total order configuration is used (e.g. {@link org.jgroups.protocols.SEQUENCER} based), lock requests for
+ * the same resource from different senders may be received in different order, so deadlocks can occur. Example:
* <pre>
* - Nodes A and B
* - A and B call lock(X) at the same time
@@ -27,8 +27,11 @@
* add SEQUENCER to the configuration, so that all lock requests are received in the same global order at both A and B,
* or use {@link java.util.concurrent.locks.Lock#tryLock(long,java.util.concurrent.TimeUnit)} with retries if a lock
* cannot be acquired.<p/>
- * An alternative is also the {@link org.jgroups.blocks.locking.CentralLockService}.
+ * An alternative is also the {@link org.jgroups.protocols.CENTRAL_LOCK} protocol.
* @author Bela Ban
+ * @since 2.12
+ * @see Locking
+ * @see CENTRAL_LOCK
*/
@Experimental
public class PEER_LOCK extends Locking {
@@ -84,10 +87,8 @@ protected synchronized void handleLockGrantedResponse(Owner owner, Address sende
if(grants.isEmpty())
return;
grants.remove(sender);
- if(grants.isEmpty()) {
+ if(grants.isEmpty())
lockGranted();
- // notifyLocked(this.name, owner);
- }
}
}

0 comments on commit c69d63e

Please sign in to comment.