condition.java

来自「SRI international 发布的OAA框架软件」· Java 代码 · 共 434 行 · 第 1/2 页

     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     * <p>If the current thread's interrupted status is set when it enters
     * this method, or it is {@link Thread#interrupt interrupted}
     * while waiting, it will continue to wait until signalled. When it finally
     * returns from this method its interrupted status will still
     * be set.
     *
     * <p><b>Implementation Considerations</b>
     * <p>The current thread is assumed to hold the lock associated with this
     * <tt>Condition</tt> when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     *
     **/
    void awaitUninterruptibly();

//    /**
//     * Causes the current thread to wait until it is signalled or interrupted,
//     * or the specified waiting time elapses.
//     *
//     * <p>The lock associated with this condition is atomically
//     * released and the current thread becomes disabled for thread scheduling
//     * purposes and lies dormant until <em>one</em> of five things happens:
//     * <ul>
//     * <li>Some other thread invokes the {@link #signal} method for this
//     * <tt>Condition</tt> and the current thread happens to be chosen as the
//     * thread to be awakened; or
//     * <li>Some other thread invokes the {@link #signalAll} method for this
//     * <tt>Condition</tt>; or
//     * <li>Some other thread {@link Thread#interrupt interrupts} the current
//     * thread, and interruption of thread suspension is supported; or
//     * <li>The specified waiting time elapses; or
//     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
//     * </ul>
//     *
//     * <p>In all cases, before this method can return the current thread must
//     * re-acquire the lock associated with this condition. When the
//     * thread returns it is <em>guaranteed</em> to hold this lock.
//     *
//     * <p>If the current thread:
//     * <ul>
//     * <li>has its interrupted status set on entry to this method; or
//     * <li>is {@link Thread#interrupt interrupted} while waiting
//     * and interruption of thread suspension is supported,
//     * </ul>
//     * then {@link InterruptedException} is thrown and the current thread's
//     * interrupted status is cleared. It is not specified, in the first
//     * case, whether or not the test for interruption occurs before the lock
//     * is released.
//     *
//     * <p>The method returns an estimate of the number of nanoseconds
//     * remaining to wait given the supplied <tt>nanosTimeout</tt>
//     * value upon return, or a value less than or equal to zero if it
//     * timed out. This value can be used to determine whether and how
//     * long to re-wait in cases where the wait returns but an awaited
//     * condition still does not hold. Typical uses of this method take
//     * the following form:
//     *
//     * <pre>
//     * synchronized boolean aMethod(long timeout, TimeUnit unit) {
//     *   long nanosTimeout = unit.toNanos(timeout);
//     *   while (!conditionBeingWaitedFor) {
//     *     if (nanosTimeout &gt; 0)
//     *         nanosTimeout = theCondition.awaitNanos(nanosTimeout);
//     *      else
//     *        return false;
//     *   }
//     *   // ...
//     * }
//     * </pre>
//     *
//     * <p> Design note: This method requires a nanosecond argument so
//     * as to avoid truncation errors in reporting remaining times.
//     * Such precision loss would make it difficult for programmers to
//     * ensure that total waiting times are not systematically shorter
//     * than specified when re-waits occur.
//     *
//     * <p><b>Implementation Considerations</b>
//     * <p>The current thread is assumed to hold the lock associated with this
//     * <tt>Condition</tt> when this method is called.
//     * It is up to the implementation to determine if this is
//     * the case and if not, how to respond. Typically, an exception will be
//     * thrown (such as {@link IllegalMonitorStateException}) and the
//     * implementation must document that fact.
//     *
//     * <p>An implementation can favor responding to an interrupt over normal
//     * method return in response to a signal, or over indicating the elapse
//     * of the specified waiting time. In either case the implementation
//     * must ensure that the signal is redirected to another waiting thread, if
//     * there is one.
//     *
//     * @param nanosTimeout the maximum time to wait, in nanoseconds
//     * @return A value less than or equal to zero if the wait has
//     * timed out; otherwise an estimate, that
//     * is strictly less than the <tt>nanosTimeout</tt> argument,
//     * of the time still remaining when this method returned.
//     *
//     * @throws InterruptedException if the current thread is interrupted (and
//     * interruption of thread suspension is supported).
//     */
//    long awaitNanos(long nanosTimeout) throws InterruptedException;

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified waiting time elapses. This method is behaviorally
     * equivalent to:<br>
     * <pre>
     *   awaitNanos(unit.toNanos(time)) &gt; 0
     * </pre>
     * @param time the maximum time to wait
     * @param unit the time unit of the <tt>time</tt> argument.
     * @return <tt>false</tt> if the waiting time detectably elapsed
     * before return from the method, else <tt>true</tt>.
     * @throws InterruptedException if the current thread is interrupted (and
     * interruption of thread suspension is supported).
     */
    boolean await(long time, TimeUnit unit) throws InterruptedException;

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified deadline elapses.
     *
     * <p>The lock associated with this condition is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of five things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * <tt>Condition</tt> and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread invokes the {@link #signalAll} method for this
     * <tt>Condition</tt>; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread, and interruption of thread suspension is supported; or
     * <li>The specified deadline elapses; or
     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
     * </ul>
     *
     * <p>In all cases, before this method can return the current thread must
     * re-acquire the lock associated with this condition. When the
     * thread returns it is <em>guaranteed</em> to hold this lock.
     *
     *
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or
     * <li>is {@link Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared. It is not specified, in the first
     * case, whether or not the test for interruption occurs before the lock
     * is released.
     *
     *
     * <p>The return value indicates whether the deadline has elapsed,
     * which can be used as follows:
     * <pre>
     * synchronized boolean aMethod(Date deadline) {
     *   boolean stillWaiting = true;
     *   while (!conditionBeingWaitedFor) {
     *     if (stillwaiting)
     *         stillWaiting = theCondition.awaitUntil(deadline);
     *      else
     *        return false;
     *   }
     *   // ...
     * }
     * </pre>
     *
     * <p><b>Implementation Considerations</b>
     * <p>The current thread is assumed to hold the lock associated with this
     * <tt>Condition</tt> when this method is called.
     * It is up to the implementation to determine if this is
     * the case and if not, how to respond. Typically, an exception will be
     * thrown (such as {@link IllegalMonitorStateException}) and the
     * implementation must document that fact.
     *
     * <p>An implementation can favor responding to an interrupt over normal
     * method return in response to a signal, or over indicating the passing
     * of the specified deadline. In either case the implementation
     * must ensure that the signal is redirected to another waiting thread, if
     * there is one.
     *
     *
     * @param deadline the absolute time to wait until
     * @return <tt>false</tt> if the deadline has
     * elapsed upon return, else <tt>true</tt>.
     *
     * @throws InterruptedException if the current thread is interrupted (and
     * interruption of thread suspension is supported).
     */
    boolean awaitUntil(Date deadline) throws InterruptedException;

    /**
     * Wakes up one waiting thread.
     *
     * <p>If any threads are waiting on this condition then one
     * is selected for waking up. That thread must then re-acquire the
     * lock before returning from <tt>await</tt>.
     **/
    void signal();

    /**
     * Wakes up all waiting threads.
     *
     * <p>If any threads are waiting on this condition then they are
     * all woken up. Each thread must re-acquire the lock before it can
     * return from <tt>await</tt>.
     **/
    void signalAll();

}