Read/write locks and lock synchronization on an object. Each object
is required to have one
ObjectLock which at any given time
may be unlocked, write locked by one transaction, or read locked
by one or more transactions.
In order to obtain a lock, the transaction must call one of the
acquire, passing itself, the lock type and the lock timeout. The
transaction must attempt to obtain only one lock at any given time
by synchronizing all calls to one of the
acquire. If the transaction
has acquired a read lock it may attempt to re-acquire the read
lock. If the transaction attempts to acquire a write lock the lock
will be upgraded.
A read lock cannot be acquired while there is a write lock on the
object, and a write lock cannot be acquired while there is one or
more read locks. If a lock cannot be acquired, the transaction
will hold until the lock is available or timeout occurs. If timeout
occured (or a dead lock has been detected),
LockNotGrantedException
is thrown. If the object has been delete
while waiting for the lock,
ObjectDeletedException
is
thrown.
When the lock is acquired, the locked object is returned.
The transaction must call
release(TransactionContext)
when the lock is no
longer required, allowing other transactions to obtain a lock. The
transaction must release all references to the object prior to
calling
release(TransactionContext)
.
If the object has been deleted, the transaction must call
delete(TransactionContext)
instead of
release(TransactionContext)
.
ACTION_CREATE
(package private) static final short ACTION_CREATE
ACTION_READ
(package private) static final short ACTION_READ
ACTION_UPDATE
(package private) static final short ACTION_UPDATE
ACTION_WRITE
(package private) static final short ACTION_WRITE
TRACE
(package private) static final boolean TRACE
idcount
(package private) static int idcount
lock
(package private) static final int[] lock
delete
(package private) void delete(TransactionContext tx)
Informs the lock that the object has been deleted by the
transaction holding the write lock. The lock on the object is
released and all transactions waiting for a lock will
terminate with an
ObjectDeletedException
.
tx
- The transaction that holds the lock
enter
(package private) void enter()
Indicate that a transaction is interested in this lock.
A transaction should call this method if it is going to
change the state of this lock (by calling acquire, update
or relase.) It method should be synchronized externally
to avoid race condition. enter and leave should be called
exactly the same number of time.
getOID
(package private) OID getOID()
Return the object's OID.
hasLock
(package private) boolean hasLock(TransactionContext tx,
boolean write)
Returns true if the transaction holds a read or write lock on
the object. This method is an efficient mean to determine whether
a lock is required, or if the object is owned by the transaction.
tx
- The transactionwrite
- True if must have a write lock
- True if the transaction has a lock on this object
isDisposable
(package private) boolean isDisposable()
Return true if this object can be safely disposed. An ObjectLock
can be safely disposed if and only if the no transaction is
holding any lock, nor any transaction isEntered.
isEntered
(package private) boolean isEntered()
Return true if there is any transaction called ,
but not yet called leave
.
isFree
(package private) boolean isFree()
Return true if and only if this lock can be safely disposed
- True if no lock and no waiting
leave
(package private) void leave()
Indicate that a transaction is not interested to change the
state of this lock anymore. (ie, will not call either acquire
update, release or delete.)
It method should be synchronized externally.
release
(package private) void release(TransactionContext tx)
Releases a lock on the object previously acquired.
A write lock cannot be downgraded into a read lock
and the transaction loses its lock on the object. Other
transactions are allowed to acquire a read/write lock on the
object.
tx
- The transaction that holds the lock
setOID
(package private) void setOID(OID oid)
Set OID of this lock to new value.
toString
public String toString()
upgrade
(package private) void upgrade(TransactionContext tx,
int timeout)
throws LockNotGrantedException,
ObjectDeletedWaitingForLockException
Acquires a lock on the object on behalf of the specified
transaction. A write lock will be acquired only if there are no
read/write locks on the object; only one write lock may be in
effect. A read lock will be acquired only if there is no write
lock on the object; multiple read locks are allowed. If the
lock cannot be acquired immediately, the thread will block
until the lock is made available or the timeout has elapsed.
If the timeout has elapsed or a dead lock has been detected,
a
LockNotGrantedException
is thrown. If the object has
been deleted while waiting for a lock, a
ObjectDeletedException
is thrown. To prevent dead locks, a
transaction must only call this method for any given object
from a single thread and must mark the lock it is trying to
acquire and return it from a call to
TransactionContext.getWaitOnLock()
if the call to this method
has not returned yet. If a read lock is available for the
transaction and a write lock is requested, the read lock is
cancelled whether or not the write is acquired.
tx
- The transaction requesting the locktimeout
- Timeout waiting to acquire lock (in milliseconds),
zero for no waiting