commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ozeigerm...@apache.org
Subject cvs commit: jakarta-commons/transaction/src/java/org/apache/commons/transaction/locking ReadWriteUpgradeLock.java ReadWriteUpgradeLockManager.java
Date Fri, 17 Dec 2004 00:30:54 GMT
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


Mime
View raw message