camera2/utils/CloseableLock.java

/*
 * Copyright (C) 2014 The Android Open Source Project
 *
 * 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 android.hardware.camera2.utils;

import android.util.Log;

import java.util.concurrent.locks.Condition;
import java.util.concurrent.locks.ReentrantLock;

/**
 * Implement a shared/exclusive lock that can be closed.
 *
 * <p>A shared lock can be acquired if any other shared locks are also acquired. An
 * exclusive lock acquire will block until all shared locks have been released.</p>
 *
 * <p>Locks are re-entrant; trying to acquire another lock (of the same type)
 * while a lock is already held will immediately succeed.</p>
 *
 * <p>Acquiring to acquire a shared lock while holding an exclusive lock or vice versa is not
 * supported; attempting it will throw an {@link IllegalStateException}.</p>
 *
 * <p>If the lock is closed, all future and current acquires will immediately return {@code null}.
 * </p>
 */
public class CloseableLock implements AutoCloseable {

    private static final boolean VERBOSE = false;

    private final String TAG = "CloseableLock";
    private final String mName;

    private volatile boolean mClosed = false;

    /** If an exclusive lock is acquired by some thread. */
    private boolean mExclusive = false;
    /**
     * How many shared locks are acquired by any thread:
     *
     * <p>Reentrant locking increments this. If an exclusive lock is held,
     * this value will stay at 0.</p>
     */
    private int mSharedLocks = 0;

    private final ReentrantLock mLock = new ReentrantLock();
    /** This condition automatically releases mLock when waiting; re-acquiring it after notify */
    private final Condition mCondition = mLock.newCondition();

    /** How many times the current thread is holding the lock */
    private final ThreadLocal<Integer> mLockCount =
        new ThreadLocal<Integer>() {
            @Override protected Integer initialValue() {
                return 0;
            }
        };

    /**
     * Helper class to release a lock at the end of a try-with-resources statement.
     */
    public class ScopedLock implements AutoCloseable {
        private ScopedLock() {}

        /** Release the lock with {@link CloseableLock#releaseLock}. */
        @Override
        public void close() {
            releaseLock();
        }
    }

    /**
     * Create a new instance; starts out with 0 locks acquired.
     */
    public CloseableLock() {
        mName = "";
    }

    /**
     * Create a new instance; starts out with 0 locks acquired.
     *
     * @param name set an optional name for logging functionality
     */
    public CloseableLock(String name) {
        mName = name;
    }

    /**
     * Acquires the lock exclusively (blocking), marks it as closed, then releases the lock.
     *
     * <p>Marking a lock as closed will fail all further acquisition attempts;
     * it will also immediately unblock all other threads currently trying to acquire a lock.</p>
     *
     * <p>This operation is idempotent; calling it more than once has no effect.</p>
     *
     * @throws IllegalStateException
     *          if an attempt is made to {@code close} while this thread has a lock acquired
     */
    @Override
    public void close() {
        if (mClosed) {
            if (VERBOSE) {
                log("close - already closed; ignoring");
            }
            return;
        }

        ScopedLock scoper = acquireExclusiveLock();
        // Already closed by another thread?
        if (scoper == null) {
            return;
        } else if (mLockCount.get() != 1) {
            // Future: may want to add a #releaseAndClose to allow this.
            throw new IllegalStateException(
                    "Cannot close while one or more acquired locks are being held by this " +
                     "thread; release all other locks first");
        }

        try {
            mLock.lock();

            mClosed = true;
            mExclusive = false;
            mSharedLocks = 0;
            mLockCount.remove();

            // Notify all threads that are waiting to unblock and return immediately
            mCondition.signalAll();
        } finally {
            mLock.unlock();
        }

        if (VERBOSE) {
            log("close - completed");
        }
    }

    /**
     * Try to acquire the lock non-exclusively, blocking until the operation completes.
     *
     * <p>If the lock has already been closed, or being closed before this operation returns,
     * the call will immediately return {@code false}.</p>
     *
     * <p>If other threads hold a non-exclusive lock (and the lock is not yet closed),
     * this operation will return immediately. If another thread holds an exclusive lock,
     * this thread will block until the exclusive lock has been released.</p>
     *
     * <p>This lock is re-entrant; acquiring more than one non-exclusive lock per thread is
     * supported, and must be matched by an equal number of {@link #releaseLock} calls.</p>
     *
     * @return {@code ScopedLock} instance if the lock was acquired, or {@code null} if the lock
     *         was already closed.
     *
     * @throws IllegalStateException if this thread is already holding an exclusive lock
     */
    public ScopedLock acquireLock() {

        int ownedLocks;

        try {
            mLock.lock();

            // Lock is already closed, all further acquisitions will fail
            if (mClosed) {
                if (VERBOSE) {
                    log("acquire lock early aborted (already closed)");
                }
                return null;
            }

            ownedLocks = mLockCount.get();

            // This thread is already holding an exclusive lock
            if (mExclusive && ownedLocks > 0) {
                throw new IllegalStateException(
                        "Cannot acquire shared lock while holding exclusive lock");
            }

            // Is another thread holding the exclusive lock? Block until we can get in.
            while (mExclusive) {
                mCondition.awaitUninterruptibly();

                // Did another thread #close while we were waiting? Unblock immediately.
                if (mClosed) {
                    if (VERBOSE) {
                        log("acquire lock unblocked aborted (already closed)");
                    }
                    return null;
                }
            }

            mSharedLocks++;

            ownedLocks = mLockCount.get() + 1;
            mLockCount.set(ownedLocks);
        } finally {
            mLock.unlock();
        }

        if (VERBOSE) {
            log("acquired lock (local own count = " + ownedLocks + ")");
        }
        return new ScopedLock();
    }

    /**
     * Try to acquire the lock exclusively, blocking until all other threads release their locks.
     *
     * <p>If the lock has already been closed, or being closed before this operation returns,
     * the call will immediately return {@code false}.</p>
     *
     * <p>If any other threads are holding a lock, this thread will block until all
     * other locks are released.</p>
     *
     * <p>This lock is re-entrant; acquiring more than one exclusive lock per thread is supported,
     * and must be matched by an equal number of {@link #releaseLock} calls.</p>
     *
     * @return {@code ScopedLock} instance if the lock was acquired, or {@code null} if the lock
     *         was already closed.
     *
     * @throws IllegalStateException
     *          if an attempt is made to acquire an exclusive lock while already holding a lock
     */
    public ScopedLock acquireExclusiveLock() {

        int ownedLocks;

        try {
            mLock.lock();

            // Lock is already closed, all further acquisitions will fail
            if (mClosed) {
                if (VERBOSE) {
                    log("acquire exclusive lock early aborted (already closed)");
                }
                return null;
            }

            ownedLocks = mLockCount.get();

            // This thread is already holding a shared lock
            if (!mExclusive && ownedLocks > 0) {
                throw new IllegalStateException(
                        "Cannot acquire exclusive lock while holding shared lock");
            }

            /*
             * Is another thread holding the lock? Block until we can get in.
             *
             * If we are already holding the lock, always let it through since
             * we are just reentering the exclusive lock.
             */
            while (ownedLocks == 0 && (mExclusive || mSharedLocks > 0)) {
                mCondition.awaitUninterruptibly();

             // Did another thread #close while we were waiting? Unblock immediately.
                if (mClosed) {
                    if (VERBOSE) {
                        log("acquire exclusive lock unblocked aborted (already closed)");
                    }
                    return null;
                }
            }

            mExclusive = true;

            ownedLocks = mLockCount.get() + 1;
            mLockCount.set(ownedLocks);
        } finally {
            mLock.unlock();
        }

        if (VERBOSE) {
            log("acquired exclusive lock (local own count = " + ownedLocks + ")");
        }
        return new ScopedLock();
    }

    /**
     * Release a single lock that was acquired.
     *
     * <p>Any other other that is blocked and trying to acquire a lock will get a chance
     * to acquire the lock.</p>
     *
     * @throws IllegalStateException if no locks were acquired, or if the lock was already closed
     */
    public void releaseLock() {
        if (mLockCount.get() <= 0) {
            throw new IllegalStateException(
                    "Cannot release lock that was not acquired by this thread");
        }

        int ownedLocks;

        try {
            mLock.lock();

            // Lock is already closed, it couldn't have been acquired in the first place
            if (mClosed) {
                throw new IllegalStateException("Do not release after the lock has been closed");
            }

            if (!mExclusive) {
                mSharedLocks--;
            } else {
                if (mSharedLocks != 0) {
                    throw new AssertionError("Too many shared locks " + mSharedLocks);
                }
            }

            ownedLocks = mLockCount.get() - 1;
            mLockCount.set(ownedLocks);

            if (ownedLocks == 0 && mExclusive) {
                // Wake up any threads that might be waiting for the exclusive lock to be released
                mExclusive = false;
                mCondition.signalAll();
            } else if (ownedLocks == 0 && mSharedLocks == 0) {
                // Wake up any threads that might be trying to get the exclusive lock
                mCondition.signalAll();
            }
        } finally {
            mLock.unlock();
        }

        if (VERBOSE) {
             log("released lock (local lock count " + ownedLocks + ")");
        }
    }

    private void log(String what) {
        Log.v(TAG + "[" + mName + "]", what);
    }

}