1 /*
2  * Copyright (C) 2014 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.camera.async;
18 
19 import java.util.concurrent.TimeUnit;
20 import java.util.concurrent.TimeoutException;
21 
22 /**
23  * An input stream of objects which can be closed from either the producer or
24  * the consumer.
25  */
26 public interface BufferQueue<T> extends SafeCloseable {
27     @Override
close()28     public void close();
29 
30     /**
31      * Blocks, returning the next available value.
32      *
33      * @return The next available value.
34      * @throws InterruptedException If interrupted while waiting for the next
35      *             value.
36      * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException If the stream is closed and no more values
37      *             will be available.
38      */
getNext()39     public T getNext() throws InterruptedException, BufferQueueClosedException;
40 
41     /**
42      * Blocks, returning the next available value.
43      *
44      * @param timeout The maximum amount of time to wait.
45      * @param unit The unit associated with the timeout.
46      * @return The next available value.
47      * @throws InterruptedException If interrupted while waiting for the next
48      *             value.
49      * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException If the stream is closed and no more values
50      *             will be available.
51      * @throws TimeoutException If no new value is made available within the
52      *             specified time limit.
53      */
getNext(long timeout, TimeUnit unit)54     public T getNext(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException,
55             BufferQueueClosedException;
56 
57     /**
58      * Immediately returns the next available value without removing it from the
59      * stream.
60      *
61      * @return The next available value if one exists, or null if no value
62      *         exists yet or the stream is closed.
63      */
peekNext()64     public T peekNext();
65 
66     /**
67      * Immediately discards the next available value, if one exists.
68      */
discardNext()69     public void discardNext();
70 
71     /**
72      * @return True if the stream has been closed by either the producer or the
73      *         consumer.
74      */
isClosed()75     public boolean isClosed();
76 
77     /**
78      * Indicates that the stream is closed and no more results are available.
79      */
80     public static class BufferQueueClosedException extends Exception {
81     }
82 }
83