001// Copyright 2012 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.commons.internal.util;
016
017import java.util.concurrent.locks.Lock;
018import java.util.concurrent.locks.ReentrantReadWriteLock;
019
020/**
021 * Base class for classes that need to manage a ReadWriteLock.
022 */
023public abstract class LockSupport
024{
025    private final Lock readLock, writeLock;
026
027    protected LockSupport()
028    {
029        ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
030
031        readLock = lock.readLock();
032        writeLock = lock.writeLock();
033    }
034
035    /**
036     * Locks the shared read lock. Any number of threads may lock the read lock at the same time.
037     */
038    protected final void acquireReadLock()
039    {
040        readLock.lock();
041    }
042
043    /**
044     * Takes the exclusive write lock. Once started, no other thread lock the read or write lock. When this method returns,
045     * this thread will have locked the write lock and no other thread will have either the read or write lock.
046     * Note that this thread must first drop the read lock (if it has it) before attempting to take the write lock, or this method will block forever.
047     */
048    protected final void takeWriteLock()
049    {
050        writeLock.lock();
051    }
052
053    /**
054     * Releases the shared read lock.
055     */
056    protected final void releaseReadLock()
057    {
058        readLock.unlock();
059    }
060
061    /**
062     * Releases the  exclusive read lock.
063     */
064    protected final void releaseWriteLock()
065    {
066        writeLock.unlock();
067    }
068
069    /**
070     * Releases the read lock, then takes the write lock. There's a short window where the thread will have neither lock:
071     * during that window, some other thread may have a chance to take the write lock. In code, you'll often see a second check
072     * inside the code that has the write lock to see if the update to perform is still necessary.
073     */
074    protected final void upgradeReadLockToWriteLock()
075    {
076        releaseReadLock();
077        // This is that instant where another thread may grab the write lock. Very rare, but possible.
078        takeWriteLock();
079    }
080
081    /**
082     * Takes the read lock then releases the write lock.
083     */
084    protected final void downgradeWriteLockToReadLock()
085    {
086        acquireReadLock();
087        releaseWriteLock();
088    }
089}