arlut.csd.ganymede
Class DBLock

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

Direct Known Subclasses:

DBDumpLock, DBReadLock, DBWriteLock

public abstract class DBLock

extends java.lang.Object

DBLocks arbitrate access to DBObjectBase objects in the Ganymede server's DBStore. Threads wishing to read from, dump, or update object bases in the DBStore must be in possession of an established DBLock. The general scheme is that any number of readers and/or dumpers can read from an object base simultaneously. If a number of readers are processing when a thread attempts to establish a write lock, those readers are allowed to complete their reading, but no new read lock may be established until the writer has a chance to get in and make its update.

If there are a number of writer locks queued up for update access to a DBObjectBase in the DBStore when a thread attempts to establish a dump lock, those writers are allowed to complete their updates, but no new writer is queued until the dump thread finishes dumping the locked bases.

All of this priority logic is implemented in the establish() methods of the concrete DBLock subclasses.

As mentioned above, all DBLock's are issued in the context of one or more DBObjectBase objects. The DBObjectBases are actually the things being locked. To maintain multi-threaded safety of the lock system across multiple DBObjectBases, the DBLock establish() and release() methods (as implemented in DBReadLock, DBWriteLock, and DBDumpLock) are all synchronized on the Ganymede's DBStore object. This synchronization is critical for the proper functioning of the DBLock system.

There is currently no support for handling timeouts, and locks can persist indefinitely. However, the GanymedeSession class will detect a client that has died, and will properly clean up any locks held by the user.

Field Summary

(package private) boolean	abort Will be true if a DBLock has had its abort() method called.
(package private) java.util.Vector	baseSet In order to prevent deadlocks, each individual lock must be established on all applicable DBObjectBases at the time the lock is initially established.
(package private) boolean	inEstablish Will be true while a DBLock is in the process of being established.
(package private) java.lang.Object	key All DBLock's have an identifier key, which is used to identify the lock in the DBStore's DBLockSync object.
(package private) boolean	locked Will be true if a DBLock is successfully locked.
(package private) arlut.csd.ganymede.DBLockSync	lockSync All DBLock's establish() and release() methods synchronize their critical sections on the DBLockSync object held in the Ganymede server's DBStore object in order to guarantee that all lock negotiations are thread-safe.

Constructor Summary

DBLock()

Method Summary

(package private) abstract void	abort() Abort this lock; if any thread is waiting in establish() on this lock when abort() is called, that thread's call to establish() will fail with an InterruptedException.
(package private) abstract void	establish(java.lang.Object key) This method waits until the lock can be established.
(package private) java.lang.Object	getKey() Returns the key that this lock is established with, or null if the lock has not been established.
(package private) boolean	isLocked() Returns true if the lock has been established and not yet aborted / released.
(package private) boolean	isLocked(arlut.csd.ganymede.DBObjectBase base) Returns true if the lock has the given DBObjectBase locked.
(package private) boolean	isLocked(java.util.Vector bases) Returns true if the lock has all of the DBObjectBase objects in the provided Vector locked.
(package private) boolean	overlaps(java.util.Vector bases) Returns true if the lock has any of the DBObjectBase objects in the provided Vector locked.
(package private) abstract void	release() Unlock the bases held by this lock.
java.lang.String	toString() Returns a string describing this lock for use in debug messages

Methods inherited from class java.lang.Object

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

Field Detail

key

java.lang.Object key

All DBLock's have an identifier key, which is used to identify the lock in the DBStore's DBLockSync object. The establish() methods in the DBLock subclasses consult the DBStore.lockSync to make sure that no DBSession ever possesses more than one write lock, to prevent deadlocks from occuring in the server.

lockSync

arlut.csd.ganymede.DBLockSync lockSync

All DBLock's establish() and release() methods synchronize their critical sections on the DBLockSync object held in the Ganymede server's DBStore object in order to guarantee that all lock negotiations are thread-safe.

baseSet

java.util.Vector baseSet

In order to prevent deadlocks, each individual lock must be established on all applicable DBObjectBases at the time the lock is initially established. baseSet is the Vector of DBObjectBases that this DBLock is/will be locked on.

locked

boolean locked

Will be true if a DBLock is successfully locked.

Should not be directly accessed outside of the DBLock class hierarchy (unfortunately Java has no support for 'accessible to subclasses only').

abort

boolean abort

Will be true if a DBLock has had its abort() method called. Once aborted, a lock may never be re-established; the locking code must create a new lock.

inEstablish

boolean inEstablish

Will be true while a DBLock is in the process of being established.

Constructor Detail

DBLock

public DBLock()

Method Detail

isLocked

boolean isLocked()

Returns true if the lock has been established and not yet aborted / released.

isLocked

boolean isLocked(arlut.csd.ganymede.DBObjectBase base)

Returns true if the lock has the given DBObjectBase locked.

isLocked

boolean isLocked(java.util.Vector bases)

Returns true if the lock has all of the DBObjectBase objects in the provided Vector locked.

overlaps

boolean overlaps(java.util.Vector bases)

Returns true if the lock has any of the DBObjectBase objects in the provided Vector locked.

establish

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

This method waits until the lock can be established. The DBObjectBases locked are specified in the constructor of the implementation subclass (DBReadLock, DBWriteLock, or DBDumpLock).

A thread that calls establish() will be suspended (waiting on the server's DBStore until all DBObjectBases listed in the DBLock's constructor are available to be locked. At that point, the thread blocking on establish() will wake up possessing a lock on the requested DBObjectBases.

It is possible for the establish() to fail completely.. the admin console may reject a client whose thread is blocking on establish(), for instance, or the server may be shut down. In those cases, another thread may call the DBLock's abort() method, in which case establish() will throw an InterruptedException, and the lock will not be established.

java.lang.InterruptedException

release

abstract void release()

Unlock the bases held by this lock.

abort

abstract void abort()

Abort this lock; if any thread is waiting in establish() on this lock when abort() is called, that thread's call to establish() will fail with an InterruptedException.

getKey

java.lang.Object getKey()

Returns the key that this lock is established with, or null if the lock has not been established.

toString

public java.lang.String toString()

Returns a string describing this lock for use in debug messages

Overrides:

toString in class java.lang.Object