/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.ignite;

import java.util.Date;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Condition;

/**
 * This interface provides a rich API for working with condition objects
 * associated with distributed reentrant locks.
 * <p>
 * <h1 class="header">Functionality</h1>
 * IgniteCondition provides functionality similar to {@code java.util.concurrent.locks.Condition}.
 */
public interface IgniteCondition extends Condition {
    /**
     * Name of ignite condition.
     *
     * @return Name of ignite condition.
     */
    public String name();

    /**
     * Causes the current thread to wait until it is signalled or
     * {@linkplain Thread#interrupt interrupted}.
     *
     * <p>The lock associated with this {@code IgniteCondition} is atomically
     * released and the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until <em>one</em> of six things happens:
     * <ul>
     * <li>Some other thread (on any node) invokes the {@link #signal} method for this
     * {@code Condition} and the current thread happens to be chosen as the
     * thread to be awakened; or
     * <li>Some other thread (on any node) invokes the {@link #signalAll} method for this
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>Some other node in grid fails, and lock is created in non-failoverSafe mode; or
     * <li>Local node is stopped; or
     * <li>A "<em>spurious wakeup</em>" occurs.
     * </ul>
     *
     * <p>If lock is not broken (because of failure of lock owner node)
     * in non-failoverSafe mode and local node is alive,
     * before this method can return the current thread must
     * re-acquire the lock associated with this condition. In all other cases
     * 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 {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link IgniteInterruptedException} 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><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @throws IgniteInterruptedException if the current thread is interrupted
     * @throws IgniteException if the node stopped, or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override void await() throws IgniteInterruptedException, IgniteException;

    /**
     * Causes the current thread to wait until it is signalled.
     *
     * <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
     * {@code Condition} 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
     * {@code Condition}; or
     * <li>Some other node in grid fails, and lock is created in non-failoverSafe mode; or
     * <li>Local node is stopped; or
     * <li>A "<em>spurious wakeup</em>" occurs.
     * </ul>
     *
     * <p>If lock is not broken (because of failure of lock owner node)
     * in non-failoverSafe mode and local node is alive,
     * before this method can return the current thread must
     * re-acquire the lock associated with this condition. In all other cases,
     * 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 {@linkplain 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
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @throws IgniteException if the node stopped, or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override void awaitUninterruptibly() throws IgniteException;

    /**
     * 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 seven things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} 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
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>The specified waiting time elapses; or
     * <li>Some other node in grid fails, and lock is created in non-failoverSafe mode; or
     * <li>Local node is stopped; or
     * <li>A "<em>spurious wakeup</em>" occurs.
     * </ul>
     *
     * <p>If lock is not broken (because of failure of lock owner node)
     * in non-failoverSafe mode and local node is alive,
     * 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 {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link IgniteInterruptedException} 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 {@code nanosTimeout}
     * 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> {@code
     * boolean aMethod(long timeout, TimeUnit unit) {
     *   long nanos = unit.toNanos(timeout);
     *   lock.lock();
     *   try {
     *     while (!conditionBeingWaitedFor()) {
     *       if (nanos <= 0L)
     *         return false;
     *       nanos = theCondition.awaitNanos(nanos);
     *     }
     *     // ...
     *   } finally {
     *     lock.unlock();
     *   }
     * }}</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
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @param nanosTimeout the maximum time to wait, in nanoseconds
     * @return an estimate of the {@code nanosTimeout} value minus
     *         the time spent waiting upon return from this method.
     *         A positive value may be used as the argument to a
     *         subsequent call to this method to finish waiting out
     *         the desired time.  A value less than or equal to zero
     *         indicates that no time remains.
     * @throws IgniteInterruptedException if the current thread is interrupted
     * @throws IgniteException if the node stopped, or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override long awaitNanos(long nanosTimeout) throws IgniteInterruptedException, IgniteException;

    /**
     * Causes the current thread to wait until it is signalled or interrupted,
     * or the specified waiting time elapses. This method is behaviorally
     * equivalent to:
     *  <pre> {@code awaitNanos(unit.toNanos(time)) > 0}</pre>
     *
     * @param time the maximum time to wait
     * @param unit the time unit of the {@code time} argument
     * @return {@code false} if the waiting time detectably elapsed
     *         before return from the method, else {@code true}
     * @throws IgniteInterruptedException if the current thread is interrupted
     * @throws IgniteException if the node stopped, or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override boolean await(long time, TimeUnit unit) throws IgniteInterruptedException, IgniteException;

    /**
     * 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 seven things happens:
     * <ul>
     * <li>Some other thread invokes the {@link #signal} method for this
     * {@code Condition} 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
     * {@code Condition}; or
     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
     * current thread, and interruption of thread suspension is supported; or
     * <li>Some other node in grid fails, and lock is created in non-failoverSafe mode; or
     * <li>Local node is stopped; or
     * <li>The specified deadline elapses; or
     * <li>A "<em>spurious wakeup</em>" occurs.
     * </ul>
     *
     * <p>If lock is not broken (because of failure of lock owner node)
     * in non-failoverSafe mode and local node is alive,
     * 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 {@linkplain Thread#interrupt interrupted} while waiting
     * and interruption of thread suspension is supported,
     * </ul>
     * then {@link IgniteInterruptedException} 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> {@code
     * boolean aMethod(Date deadline) {
     *   boolean stillWaiting = true;
     *   lock.lock();
     *   try {
     *     while (!conditionBeingWaitedFor()) {
     *       if (!stillWaiting)
     *         return false;
     *       stillWaiting = theCondition.awaitUntil(deadline);
     *     }
     *     // ...
     *   } finally {
     *     lock.unlock();
     *   }
     * }}</pre>
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @param deadline the absolute time to wait until
     * @return {@code false} if the deadline has elapsed upon return, else
     *         {@code true}
     * @throws IgniteInterruptedException if the current thread is interrupted
     *         (and interruption of thread suspension is supported)
     * @throws IgniteException if the node stopped, or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override boolean awaitUntil(Date deadline) throws IgniteInterruptedException, IgniteException;

    /**
     * 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 {@code await}.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @throws IgniteException if node is stopped or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override void signal() throws IgniteException;

    /**
     * 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 {@code await}.
     *
     * <p><b>Implementation Considerations</b>
     *
     * <p>The current thread is assumed to hold the lock associated with this
     * {@code Condition} when this method is called. If not, an {@link IllegalMonitorStateException}
     * will be thrown.
     *
     * @throws IgniteException if node is stopped or
     *         node owning the lock failed in non-failoversafe mode
     */
    @Override void signalAll() throws IgniteException;
}