FileDocCategorySizeDatePackage
CloseableLock.javaAPI DocAndroid 5.1 API11693Thu Mar 12 22:22:10 GMT 2015android.hardware.camera2.utils

CloseableLock

public class CloseableLock extends Object implements AutoCloseable
Implement a shared/exclusive lock that can be closed.

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.

Locks are re-entrant; trying to acquire another lock (of the same type) while a lock is already held will immediately succeed.

Acquiring to acquire a shared lock while holding an exclusive lock or vice versa is not supported; attempting it will throw an {@link IllegalStateException}.

If the lock is closed, all future and current acquires will immediately return {@code null}.

Fields Summary
private static final boolean
VERBOSE
private final String
TAG
private final String
mName
private volatile boolean
mClosed
private boolean
mExclusive
If an exclusive lock is acquired by some thread.
private int
mSharedLocks
How many shared locks are acquired by any thread:

Reentrant locking increments this. If an exclusive lock is held, this value will stay at 0.

private final ReentrantLock
mLock
private final Condition
mCondition
This condition automatically releases mLock when waiting; re-acquiring it after notify
private final ThreadLocal
mLockCount
How many times the current thread is holding the lock
Constructors Summary
public CloseableLock()
Create a new instance; starts out with 0 locks acquired.

        mName = "";
public CloseableLock(String name)
Create a new instance; starts out with 0 locks acquired.

param
name set an optional name for logging functionality

        mName = name;
Methods Summary
public android.hardware.camera2.utils.CloseableLock$ScopedLockacquireExclusiveLock()
Try to acquire the lock exclusively, blocking until all other threads release their locks.

If the lock has already been closed, or being closed before this operation returns, the call will immediately return {@code false}.

If any other threads are holding a lock, this thread will block until all other locks are released.

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.

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


        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();
public android.hardware.camera2.utils.CloseableLock$ScopedLockacquireLock()
Try to acquire the lock non-exclusively, blocking until the operation completes.

If the lock has already been closed, or being closed before this operation returns, the call will immediately return {@code false}.

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.

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.

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


        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();
public voidclose()
Acquires the lock exclusively (blocking), marks it as closed, then releases the lock.

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.

This operation is idempotent; calling it more than once has no effect.

throws
IllegalStateException if an attempt is made to {@code close} while this thread has a lock acquired

        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");
        }
private voidlog(java.lang.String what)

        Log.v(TAG + "[" + mName + "]", what);
public voidreleaseLock()
Release a single lock that was acquired.

Any other other that is blocked and trying to acquire a lock will get a chance to acquire the lock.

throws
IllegalStateException if no locks were acquired, or if the lock was already closed

        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 + ")");
        }