You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by oz...@apache.org on 2004/12/17 01:30:54 UTC
cvs commit: jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking ReadWriteUpgradeLock.java ReadWriteUpgradeLockManager.java
ozeigermann 2004/12/16 16:30:54
Added: transaction/src/java/org/apache/commons/transaction/locking
ReadWriteUpgradeLock.java
ReadWriteUpgradeLockManager.java
Log:
Added read/write/upgrade locks using new preference mechanism of
GenericLock.
Revision Changes Path
1.1 jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking/ReadWriteUpgradeLock.java
Index: ReadWriteUpgradeLock.java
===================================================================
/*
* $Header: /home/cvs/jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking/ReadWriteUpgradeLock.java,v 1.1 2004/12/17 00:30:54 ozeigermann Exp $
* $Revision: 1.1 $
* $Date: 2004/12/17 00:30:54 $
*
* ====================================================================
*
* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.commons.transaction.locking;
import org.apache.commons.transaction.util.LoggerFacade;
/**
* Convenience implementation of a read/write lock with an option for upgrade
* based on {@link ReadWriteUpgradeLockLock}.<br>
* <br>
* Reads are shared which means there can be any number of concurrent read
* accesses allowed by this lock. Writes are exclusive. This means when there is
* a write access no other access neither read nor write are allowed by this
* lock. <br>
* <br>
* <p>
* The idea (as explained by Jim LoVerde) on an upgrade lock is that only one owner can hold an
* upgrade lock, but while that is held, it is possible for read locks to exist
* and/or be obtained, and when the request is made to upgrade to a write lock
* by the same owner, the lock manager prevents additional read locks until the
* write lock can be aquired.
* </p>
* <p>
* In this sense the write lock becomes preferred over all other locks when it gets upgraded from
* a upgrate lock. Preferred means that if it has to wait and others wait as well it will be
* served before all other none preferred locking requests.
* </p>
*
* Calls to {@link #acquireRead(Object, long)}, {@link #acquireUpgrade(Object, long)} and
* {@link #acquireWrite(Object, long)} are blocking and reentrant. Blocking
* means they will wait if they can not acquire the descired access, reentrant
* means that a lock request by a specific owner will always be compatible with
* other accesses on this lock by the same owner. E.g. if you already have a
* lock for writing and you try to acquire write access again you will not be
* blocked by this first lock, while others of course will be. This is the
* natural way you already know from Java monitors and synchronized blocks.
*
* @version $Revision: 1.1 $
*
* @see GenericLock
* @see org.apache.commons.transaction.locking.ReadWriteLock
* @see ReadWriteUpgradeLockManager
*/
public class ReadWriteUpgradeLock extends GenericLock {
public static final int NO_LOCK = 0;
public static final int READ_LOCK = 1;
public static final int UPGRADE_LOCK = 2;
public static final int WRITE_LOCK = 3;
/**
* Creates a new read/write/upgrade lock.
*
* @param resourceId
* identifier for the resource associated to this lock
* @param logger
* generic logger used for all kind of debug logging
*/
public ReadWriteUpgradeLock(Object resourceId, LoggerFacade logger) {
super(resourceId, WRITE_LOCK, logger);
}
/**
* Tries to acquire a blocking, reentrant read lock. A read lock is
* compatible with other read locks, but not with a write lock.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire a
* certain lock level on this lock
* @param timeoutMSecs
* if blocking is enabled by the <code>wait</code> parameter
* this specifies the maximum wait time in milliseconds
* @return <code>true</code> if the lock actually was acquired
* @throws InterruptedException
* when the thread waiting on this method is interrupted
*/
public boolean acquireRead(Object ownerId, long timeoutMSecs) throws InterruptedException {
return acquire(ownerId, READ_LOCK, true, true, timeoutMSecs);
}
/**
* Tries to acquire a reentrant upgrade lock on a resource. <br>
*
* @param ownerId
* a unique id identifying the entity that wants to acquire a
* certain lock level on this lock
* @param timeoutMSecs
* if blocking is enabled by the <code>wait</code> parameter
* this specifies the maximum wait time in milliseconds
* @return <code>true</code> if the lock actually was acquired
* @throws InterruptedException
* when the thread waiting on this method is interrupted
*/
public boolean acquireUpgrade(Object ownerId, long timeoutMSecs) throws InterruptedException {
return acquire(ownerId, UPGRADE_LOCK, true, true, timeoutMSecs);
}
/**
* Tries to acquire a blocking, reentrant write lock. A write lock is
* incompatible with any another read or write lock and is thus exclusive.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire a
* certain lock level on this lock
* @param timeoutMSecs
* if blocking is enabled by the <code>wait</code> parameter
* this specifies the maximum wait time in milliseconds
* @return <code>true</code> if the lock actually was acquired
* @throws InterruptedException
* when the thread waiting on this method is interrupted
*/
public boolean acquireWrite(Object ownerId, long timeoutMSecs) throws InterruptedException {
// in case we already had an upgrade lock, this wait lock will become preferred
boolean preferred = getLockLevel(ownerId) == UPGRADE_LOCK;
return acquire(ownerId, WRITE_LOCK, true, COMPATIBILITY_REENTRANT, preferred, timeoutMSecs);
}
/**
* @see GenericLock#acquire(Object, int, boolean, boolean, long)
*/
public synchronized boolean acquire(Object ownerId, int targetLockLevel, boolean wait,
boolean reentrant, long timeoutMSecs) throws InterruptedException {
boolean preferred = (targetLockLevel == WRITE_LOCK && getLockLevel(ownerId) == UPGRADE_LOCK);
return acquire(ownerId, targetLockLevel, wait, reentrant ? COMPATIBILITY_REENTRANT
: COMPATIBILITY_NONE, preferred, timeoutMSecs);
}
}
1.1 jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking/ReadWriteUpgradeLockManager.java
Index: ReadWriteUpgradeLockManager.java
===================================================================
/*
* $Header: /home/cvs/jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking/ReadWriteUpgradeLockManager.java,v 1.1 2004/12/17 00:30:54 ozeigermann Exp $
* $Revision: 1.1 $
* $Date: 2004/12/17 00:30:54 $
*
* ====================================================================
*
* Copyright 1999-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
package org.apache.commons.transaction.locking;
import org.apache.commons.transaction.util.LoggerFacade;
/**
* Manager for
* {@link org.apache.commons.transaction.locking.ReadWriteUpgradeLock}s on
* resources. <br>
* <br>
* <p>
* The idea (as explained by Jim LoVerde) is that only one owner can hold an
* upgrade lock, but while that is held, it is possible for read locks to exist
* and/or be obtained, and when the request is made to upgrade to a write lock
* by the same owner, the lock manager prevents additional read locks until the
* write lock can be aquired.
* </p>
* <p>
* In this sense the write lock becomes preferred over all other locks when it gets upgraded from
* a upgrate lock. Preferred means that if it has to wait and others wait as well it will be
* served before all other none preferred locking requests.
* </p>
*
* @version $Revision: 1.1 $
*
* @see ReadWriteUpgradeLock
*/
public class ReadWriteUpgradeLockManager extends ReadWriteLockManager {
/**
* Creates a new read/write/upgrade lock manager.
*
* @param logger generic logger used for all kind of debug logging
* @param timeoutMSecs specifies the maximum time to wait for a lock in milliseconds
*/
public ReadWriteUpgradeLockManager(LoggerFacade logger, long timeoutMSecs) {
super(ReadWriteUpgradeLock.WRITE_LOCK, logger, timeoutMSecs);
}
/**
* Tries to acquire a reentrant upgrade lock on a resource. <br>
* <br>
* This method does not block, but immediatly returns. If a lock is not
* available <code>false</code> will be returned.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire this
* lock
* @param resourceId
* the resource to get the lock for
* @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
*/
public boolean tryUpgradeLock(Object ownerId, Object resourceId) {
return tryLock(ownerId, resourceId, ReadWriteUpgradeLock.UPGRADE_LOCK, true);
}
/**
* Tries to acquire an exclusive, reentrant write lock on a resource. <br>
* <br>
* This method does not block, but immediatly returns. If a lock is not
* available <code>false</code> will be returned.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire this
* lock
* @param resourceId
* the resource to get the lock for
* @return <code>true</code> if the lock has been acquired, <code>false</code> otherwise
*/
public boolean tryWriteLock(Object ownerId, Object resourceId) {
return tryLock(ownerId, resourceId, ReadWriteUpgradeLock.WRITE_LOCK, true);
}
/**
* Tries to acquire a reentrant upgrade lock on a resource. <br>
* <br>
* This method blocks and waits for the lock in case it is not avaiable. If
* there is a timeout or a deadlock or the thread is interrupted a
* LockException is thrown.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire this
* lock
* @param resourceId
* the resource to get the level for
* @throws LockException
* will be thrown when the lock can not be acquired
*/
public void upgradeLock(Object ownerId, Object resourceId) throws LockException {
super.lock(ownerId, resourceId, ReadWriteUpgradeLock.UPGRADE_LOCK, true);
}
/**
* Tries to acquire an exclusive, reentrant write lock on a resource. <br>
* <br>
* This method blocks and waits for the lock in case it is not avaiable. If
* there is a timeout or a deadlock or the thread is interrupted a
* LockException is thrown.
*
* @param ownerId
* a unique id identifying the entity that wants to acquire this
* lock
* @param resourceId
* the resource to get the level for
* @throws LockException
* will be thrown when the lock can not be acquired
*/
public void writeLock(Object ownerId, Object resourceId) throws LockException {
super.lock(ownerId, resourceId, ReadWriteUpgradeLock.WRITE_LOCK, true);
}
protected GenericLock createLock(Object resourceId) {
synchronized (globalLocks) {
GenericLock lock = new ReadWriteUpgradeLock(resourceId, logger);
globalLocks.put(resourceId, lock);
return lock;
}
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org