package java.lang.ref;

import ej.annotation.Nullable;

/**
 * Reference queues, to which registered reference objects are appended by the garbage collector
 * after the appropriate reachability changes are detected.
 *
 * @param <T> the type of the referenced objects
 */
public class ReferenceQueue<T> {

    /**
     * Constructs a new reference-object queue.
     */
    public ReferenceQueue() {
        throw new RuntimeException();
    }

    /**
     * Polls this queue to see if a reference object is available. If one is available without further
     * delay then it is removed from the queue and returned. Otherwise this method immediately returns
     * <code>null</code>.
     *
     * @return A reference object, if one was immediately available, otherwise <code>null</code>
     */
    @Nullable
    public Reference<? extends T> poll() {
        throw new RuntimeException();
    }

    /**
     * Removes the next reference object in this queue, blocking until one becomes available.
     *
     * @return A reference object, blocking until one becomes available
     * @throws InterruptedException
     *         If the wait is interrupted
     */
    public Reference<? extends T> remove() throws InterruptedException {
        throw new RuntimeException();
    }

    /**
     * Removes the next reference object in this queue, blocking until either one becomes available or
     * the given timeout period expires.
     *
     * <p>
     * This method does not offer real-time guarantees: It schedules the timeout as if by invoking the
     * {@link Object#wait(long)} method.
     *
     * @param timeout
     *        If positive, block for up to <code>timeout</code> milliseconds while waiting for a
     *        reference to be added to this queue. If zero, block indefinitely.
     *
     * @return A reference object, if one was available within the specified timeout period, otherwise
     *         <code>null</code>
     *
     * @throws IllegalArgumentException
     *         If the value of the timeout argument is negative
     *
     * @throws InterruptedException
     *         If the timeout wait is interrupted
     */
    @Nullable
    public Reference<? extends T> remove(long timeout) throws IllegalArgumentException, InterruptedException {
        throw new RuntimeException();
    }
}