camera2/utils/StateWaiter.java

/*
 * Copyright 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 com.android.ex.camera2.utils;

import android.os.SystemClock;
import android.util.Log;

import com.android.ex.camera2.exceptions.TimeoutRuntimeException;

import java.util.Arrays;
import java.util.Collection;
import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * Block until a specific state change occurs.
 *
 * <p>Provides wait calls that block until the next unobserved state of the
 * requested type arrives. Unobserved states are states that have occurred since
 * the last wait, or that will be received from the camera device in the
 * future.</p>
 *
 * <p>Thread interruptions are not supported; interrupting a thread that is either
 * waiting with {@link #waitForState} / {@link #waitForAnyOfStates} or is currently in
 * {@link StateChangeListener#onStateChanged} (provided by {@link #getListener}) will result in an
 * {@link UnsupportedOperationException} being raised on that thread.</p>
 */
public final class StateWaiter {

    private static final String TAG = "StateWaiter";
    private static final boolean VERBOSE = Log.isLoggable(TAG, Log.VERBOSE);

    private final String[] mStateNames;
    private final int mStateCount;
    private final StateChangeListener mListener;

    /** Guard waitForState, waitForAnyState to only have one waiter */
    private final AtomicBoolean mWaiting = new AtomicBoolean(false);

    private final LinkedBlockingQueue<Integer> mQueuedStates = new LinkedBlockingQueue<>();

    /**
     * Create a new state waiter.
     *
     * <p>All {@code state}/{@code states} arguments used in other methods must be
     * in the range of {@code [0, stateNames.length - 1]}.</p>
     *
     * @param stateNames an array of string names, used to mark the range of the valid states
     */
    public StateWaiter(String[] stateNames) {
        mStateCount = stateNames.length;
        mStateNames = new String[mStateCount];
        System.arraycopy(stateNames, /*srcPos*/0, mStateNames, /*dstPos*/0, mStateCount);

        mListener = new StateChangeListener() {
            @Override
            public void onStateChanged(int state) {
                queueStateTransition(checkStateInRange(state));
            }
        };
    }

    public StateChangeListener getListener() {
        return mListener;
    }

    /**
     * Wait until the desired state is observed, checking all state
     * transitions since the last time a state was waited on.
     *
     * <p>Any intermediate state transitions that is not {@code state} are ignored.</p>
     *
     * <p>Note: Only one waiter allowed at a time!</p>
     *
     * @param desired state to observe a transition to
     * @param timeoutMs how long to wait in milliseconds
     *
     * @throws IllegalArgumentException if {@code state} was out of range
     * @throws TimeoutRuntimeException if the desired state is not observed before timeout.
     * @throws IllegalStateException if another thread is already waiting for a state transition
     */
    public void waitForState(int state, long timeoutMs) {
        Integer[] stateArray = { checkStateInRange(state) };

        waitForAnyOfStates(Arrays.asList(stateArray), timeoutMs);
    }

    /**
     * Wait until the one of the desired {@code states} is observed, checking all
     * state transitions since the last time a state was waited on.
     *
     * <p>Any intermediate state transitions that are not in {@code states} are ignored.</p>
     *
     * <p>Note: Only one waiter allowed at a time!</p>
     *
     * @param states Set of desired states to observe a transition to.
     * @param timeoutMs how long to wait in milliseconds
     *
     * @return the state reached
     *
     * @throws IllegalArgumentException if {@code state} was out of range
     * @throws TimeoutRuntimeException if none of the states is observed before timeout.
     * @throws IllegalStateException if another thread is already waiting for a state transition
     */
    public int waitForAnyOfStates(Collection<Integer> states, final long timeoutMs) {
        checkStateCollectionInRange(states);

        // Acquire exclusive waiting privileges
        if (mWaiting.getAndSet(true)) {
            throw new IllegalStateException("Only one waiter allowed at a time");
        }

        Integer nextState = null;
        try {
            if (VERBOSE) {
                StringBuilder s = new StringBuilder("Waiting for state(s) ");
                appendStateNames(s, states);
                Log.v(TAG, s.toString());
            }

            long timeoutLeft = timeoutMs;
            long startMs = SystemClock.elapsedRealtime();
            while ((nextState = mQueuedStates.poll(timeoutLeft, TimeUnit.MILLISECONDS)) != null) {
                if (VERBOSE) {
                    Log.v(TAG, "  Saw transition to " + getStateName(nextState));
                }

                if (states.contains(nextState)) {
                    break;
                }

                long endMs = SystemClock.elapsedRealtime();
                timeoutLeft -= (endMs - startMs);
                startMs = endMs;
            }
        } catch (InterruptedException e) {
            throw new UnsupportedOperationException("Does not support interrupts on waits", e);
        } finally {
            // Release exclusive waiting privileges
            mWaiting.set(false);
        }

        if (!states.contains(nextState)) {
            StringBuilder s = new StringBuilder("Timed out after ");
            s.append(timeoutMs);
            s.append(" ms waiting for state(s) ");
            appendStateNames(s, states);

            throw new TimeoutRuntimeException(s.toString());
        }

        return nextState;
    }

    /**
     * Convert state integer to a String
     */
    public String getStateName(int state) {
        return mStateNames[checkStateInRange(state)];
    }

    /**
     * Append all states to string
     */
    public void appendStateNames(StringBuilder s, Collection<Integer> states) {
        checkStateCollectionInRange(states);

        boolean start = true;
        for (Integer state : states) {
            if (!start) {
                s.append(" ");
            }

            s.append(getStateName(state));
            start = false;
        }
    }

    private void queueStateTransition(int state) {
        if (VERBOSE) Log.v(TAG, "setCurrentState - state now " + getStateName(state));

        try {
            mQueuedStates.put(state);
        } catch(InterruptedException e) {
            throw new UnsupportedOperationException("Unable to set current state", e);
        }
    }

    private int checkStateInRange(int state) {
        if (state < 0 || state >= mStateCount) {
            throw new IllegalArgumentException("State out of range " + state);
        }

        return state;
    }

    private Collection<Integer> checkStateCollectionInRange(Collection<Integer> states) {
        for (int state : states) {
            checkStateInRange(state);
        }

        return states;
    }

}