arlut.csd.ganymede
Class DBReadLock

java.lang.Object
  |
  +--arlut.csd.ganymede.DBLock
        |
        +--arlut.csd.ganymede.DBReadLock

public class DBReadLock

extends DBLock

DBReadLock is a class used in the Ganymede server to represent a read lock on one or more DBObjectBase objects. A DBReadLock is used in the GanymedeSession class to guarantee that all query operations go from start to finish without any changes being made along the way.

While a DBReadLock is established on a DBObjectBase, no changes may be made to that base. The DBWriteLock's establish() method will suspend until all read locks on a base are cleared. As soon as a thread attempts to establish a DBWriteLock on a base, no more DBReadLocks will be established on that base until the DBWriteLock is cleared, but any DBReadLocks already established will persist until released, whereupon the DBWriteLock will establish.

See DBLock, DBWriteLock, and DBDumpLock for details.

Field Summary

(package private) static boolean

debug

Fields inherited from class arlut.csd.ganymede.DBLock

abort, baseSet, inEstablish, key, locked, lockSync

Constructor Summary

DBReadLock(DBStore store)
constructor to get a read lock on all the object bases

DBReadLock(DBStore store, java.util.Vector baseSet)
constructor to get a read lock on a subset of the object bases.

Method Summary

void	abort() Withdraw this lock.
void	establish(java.lang.Object key) Establish a read lock on bases specified in this DBReadLock's constructor.
void	release() Relinquish the lock on bases held by this lock object.

Methods inherited from class arlut.csd.ganymede.DBLock

getKey, isLocked, isLocked, isLocked, overlaps, toString

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

debug

static final boolean debug

Constructor Detail

DBReadLock

public DBReadLock(DBStore store)

constructor to get a read lock on all the object bases

DBReadLock

public DBReadLock(DBStore store,
                  java.util.Vector baseSet)

constructor to get a read lock on a subset of the object bases.

Method Detail

establish

public void establish(java.lang.Object key)
               throws java.lang.InterruptedException

Establish a read lock on bases specified in this DBReadLock's constructor. Can throw InterruptedException if another thread orders us to abort() while we're waiting for permission to proceed with reads on the specified baseset.

Overrides:

establish in class DBLock

release

public void release()

Relinquish the lock on bases held by this lock object.

Should be called by DBSession's releaseLock() method.

Note that this method is designed to be able to be called from one thread while another is trying to use and/or establish the lock. If this.abort is not set to true before calling release(), release() will block until the establish is granted. That's why abort() sets this.abort to true before calling release().

The point of release() is to clear out this lock's connections to the locked object bases and to allow DBLock establish() methods in other threads to proceed.

Overrides:

release in class DBLock

abort

public void abort()

Withdraw this lock. This method can be called by a thread to interrupt a lock establish that is blocked waiting to get access to the appropriate set of DBObjectBase objects. If this method is called while another thread is blocked in establish(), establish() will throw an InterruptedException.

Once abort() is processed, this lock may never be established. Any subsequent calls to establish() will always throw InterruptedException.

Note that calling abort() on a lock that has already established in another thread will remove the lock, but a thread that is using the lock to iterate over a list will explicitly need to check to see if its lock was pulled. queryDispatch() and getObjects() both do this properly, so it is generally safe to abort read locks in the GanymedeServer as needed.

Overrides:

abort in class DBLock