/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Written by Doug Lea with assistance from members of JCP JSR-166

 * Expert Group and released to the public domain, as explained at

 * http://creativecommons.org/licenses/publicdomain

 */

package java.util.concurrent.locks;

import java.util.concurrent.TimeUnit;

/**

 * {@code Lock} implementations provide more extensive locking

 * operations than can be obtained using {@code synchronized} methods

 * and statements.  They allow more flexible structuring, may have

 * quite different properties, and may support multiple associated

 * {@link Condition} objects.

 *

 * <p>A lock is a tool for controlling access to a shared resource by

 * multiple threads. Commonly, a lock provides exclusive access to a

 * shared resource: only one thread at a time can acquire the lock and

 * all access to the shared resource requires that the lock be

 * acquired first. However, some locks may allow concurrent access to

 * a shared resource, such as the read lock of a {@link ReadWriteLock}.

 *

 * <p>The use of {@code synchronized} methods or statements provides

 * access to the implicit monitor lock associated with every object, but

 * forces all lock acquisition and release to occur in a block-structured way:

 * when multiple locks are acquired they must be released in the opposite

 * order, and all locks must be released in the same lexical scope in which

 * they were acquired.

 *

 * <p>While the scoping mechanism for {@code synchronized} methods

 * and statements makes it much easier to program with monitor locks,

 * and helps avoid many common programming errors involving locks,

 * there are occasions where you need to work with locks in a more

 * flexible way. For example, some algorithms for traversing

 * concurrently accessed data structures require the use of

 * "hand-over-hand" or "chain locking": you

 * acquire the lock of node A, then node B, then release A and acquire

 * C, then release B and acquire D and so on.  Implementations of the

 * {@code Lock} interface enable the use of such techniques by

 * allowing a lock to be acquired and released in different scopes,

 * and allowing multiple locks to be acquired and released in any

 * order.

 *

 * <p>With this increased flexibility comes additional

 * responsibility. The absence of block-structured locking removes the

 * automatic release of locks that occurs with {@code synchronized}

 * methods and statements. In most cases, the following idiom

 * should be used:

 *

 * <pre><tt>     Lock l = ...;

 *     l.lock();

 *     try {

 *         // access the resource protected by this lock

 *     } finally {

 *         l.unlock();

 *     }

 * </tt></pre>

 *

 * When locking and unlocking occur in different scopes, care must be

 * taken to ensure that all code that is executed while the lock is

 * held is protected by try-finally or try-catch to ensure that the

 * lock is released when necessary.

 *

 * <p>{@code Lock} implementations provide additional functionality

 * over the use of {@code synchronized} methods and statements by

 * providing a non-blocking attempt to acquire a lock ({@link

 * #tryLock()}), an attempt to acquire the lock that can be

 * interrupted ({@link #lockInterruptibly}, and an attempt to acquire

 * the lock that can timeout ({@link #tryLock(long, TimeUnit)}).

 *

 * <p>A {@code Lock} class can also provide behavior and semantics

 * that is quite different from that of the implicit monitor lock,

 * such as guaranteed ordering, non-reentrant usage, or deadlock

 * detection. If an implementation provides such specialized semantics

 * then the implementation must document those semantics.

 *

 * <p>Note that {@code Lock} instances are just normal objects and can

 * themselves be used as the target in a {@code synchronized} statement.

 * Acquiring the

 * monitor lock of a {@code Lock} instance has no specified relationship

 * with invoking any of the {@link #lock} methods of that instance.

 * It is recommended that to avoid confusion you never use {@code Lock}

 * instances in this way, except within their own implementation.

 *

 * <p>Except where noted, passing a {@code null} value for any

 * parameter will result in a {@link NullPointerException} being

 * thrown.

 *

 * <h3>Memory Synchronization</h3>

 *

 * <p>All {@code Lock} implementations <em>must</em> enforce the same

 * memory synchronization semantics as provided by the built-in monitor

 * lock, as described in <a href="http://java.sun.com/docs/books/jls/">

 * The Java Language Specification, Third Edition (17.4 Memory Model)</a>:

 * <ul>

 * <li>A successful {@code lock} operation has the same memory

 * synchronization effects as a successful <em>Lock</em> action.

 * <li>A successful {@code unlock} operation has the same

 * memory synchronization effects as a successful <em>Unlock</em> action.

 * </ul>

 *

 * Unsuccessful locking and unlocking operations, and reentrant

 * locking/unlocking operations, do not require any memory

 * synchronization effects.

 *

 * <h3>Implementation Considerations</h3>

 *

 * <p> The three forms of lock acquisition (interruptible,

 * non-interruptible, and timed) may differ in their performance

 * characteristics, ordering guarantees, or other implementation

 * qualities.  Further, the ability to interrupt the <em>ongoing</em>

 * acquisition of a lock may not be available in a given {@code Lock}

 * class.  Consequently, an implementation is not required to define

 * exactly the same guarantees or semantics for all three forms of

 * lock acquisition, nor is it required to support interruption of an

 * ongoing lock acquisition.  An implementation is required to clearly

 * document the semantics and guarantees provided by each of the

 * locking methods. It must also obey the interruption semantics as

 * defined in this interface, to the extent that interruption of lock

 * acquisition is supported: which is either totally, or only on

 * method entry.

 *

 * <p>As interruption generally implies cancellation, and checks for

 * interruption are often infrequent, an implementation can favor responding

 * to an interrupt over normal method return. This is true even if it can be

 * shown that the interrupt occurred after another action may have unblocked

 * the thread. An implementation should document this behavior.

 *

 * @see ReentrantLock

 * @see Condition

 * @see ReadWriteLock

 *

 * @since 1.5

 * @author Doug Lea

 */

public interface Lock {

    /**

     * Acquires the lock.

     *

     * <p>If the lock is not available then the current thread becomes

     * disabled for thread scheduling purposes and lies dormant until the

     * lock has been acquired.

     *

     * <p><b>Implementation Considerations</b>

     *

     * <p>A {@code Lock} implementation may be able to detect erroneous use

     * of the lock, such as an invocation that would cause deadlock, and

     * may throw an (unchecked) exception in such circumstances.  The

     * circumstances and the exception type must be documented by that

     * {@code Lock} implementation.

     */

    void lock();

    /**

     * Acquires the lock unless the current thread is

     * {@linkplain Thread#interrupt interrupted}.

     *

     * <p>Acquires the lock if it is available and returns immediately.

     *

     * <p>If the lock is not available then the current thread becomes

     * disabled for thread scheduling purposes and lies dormant until

     * one of two things happens:

     *

     * <ul>

     * <li>The lock is acquired by the current thread; or

     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the

     * current thread, and interruption of lock acquisition is supported.

     * </ul>

     *

     * <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 acquiring the

     * lock, and interruption of lock acquisition is supported,

     * </ul>

     * then {@link InterruptedException} is thrown and the current thread's

     * interrupted status is cleared.

     *

     * <p><b>Implementation Considerations</b>

     *

     * <p>The ability to interrupt a lock acquisition in some

     * implementations may not be possible, and if possible may be an

     * expensive operation.  The programmer should be aware that this

     * may be the case. An implementation should document when this is

     * the case.

     *

     * <p>An implementation can favor responding to an interrupt over

     * normal method return.

     *

     * <p>A {@code Lock} implementation may be able to detect

     * erroneous use of the lock, such as an invocation that would

     * cause deadlock, and may throw an (unchecked) exception in such

     * circumstances.  The circumstances and the exception type must

     * be documented by that {@code Lock} implementation.

     *

     * @throws InterruptedException if the current thread is

     *         interrupted while acquiring the lock (and interruption

     *         of lock acquisition is supported).

     */

    void lockInterruptibly() throws InterruptedException;

    /**

     * Acquires the lock only if it is free at the time of invocation.

     *

     * <p>Acquires the lock if it is available and returns immediately

     * with the value {@code true}.

     * If the lock is not available then this method will return

     * immediately with the value {@code false}.

     *

     * <p>A typical usage idiom for this method would be:

     * <pre>

     *      Lock lock = ...;

     *      if (lock.tryLock()) {

     *          try {

     *              // manipulate protected state

     *          } finally {

     *              lock.unlock();

     *          }

     *      } else {

     *          // perform alternative actions

     *      }

     * </pre>

     * This usage ensures that the lock is unlocked if it was acquired, and

     * doesn't try to unlock if the lock was not acquired.

     *

     * @return {@code true} if the lock was acquired and

     *         {@code false} otherwise

     */

    boolean tryLock();

    /**

     * Acquires the lock if it is free within the given waiting time and the

     * current thread has not been {@linkplain Thread#interrupt interrupted}.

     *

     * <p>If the lock is available this method returns immediately

     * with the value {@code true}.

     * If the lock is not available then

     * the current thread becomes disabled for thread scheduling

     * purposes and lies dormant until one of three things happens:

     * <ul>

     * <li>The lock is acquired by the current thread; or

     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the

     * current thread, and interruption of lock acquisition is supported; or

     * <li>The specified waiting time elapses

     * </ul>

     *

     * <p>If the lock is acquired then the value {@code true} is returned.

     *

     * <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 acquiring

     * the lock, and interruption of lock acquisition is supported,

     * </ul>

     * then {@link InterruptedException} is thrown and the current thread's

     * interrupted status is cleared.

     *

     * <p>If the specified waiting time elapses then the value {@code false}

     * is returned.

     * If the time is

     * less than or equal to zero, the method will not wait at all.

     *

     * <p><b>Implementation Considerations</b>

     *

     * <p>The ability to interrupt a lock acquisition in some implementations

     * may not be possible, and if possible may

     * be an expensive operation.

     * The programmer should be aware that this may be the case. An

     * implementation should document when this is the case.

     *

     * <p>An implementation can favor responding to an interrupt over normal

     * method return, or reporting a timeout.

     *

     * <p>A {@code Lock} implementation may be able to detect

     * erroneous use of the lock, such as an invocation that would cause

     * deadlock, and may throw an (unchecked) exception in such circumstances.

     * The circumstances and the exception type must be documented by that

     * {@code Lock} implementation.

     *

     * @param time the maximum time to wait for the lock

     * @param unit the time unit of the {@code time} argument

     * @return {@code true} if the lock was acquired and {@code false}

     *         if the waiting time elapsed before the lock was acquired

     *

     * @throws InterruptedException if the current thread is interrupted

     *         while acquiring the lock (and interruption of lock

     *         acquisition is supported)

     */

    boolean tryLock(long time, TimeUnit unit) throws InterruptedException;

    /**

     * Releases the lock.

     *

     * <p><b>Implementation Considerations</b>

     *

     * <p>A {@code Lock} implementation will usually impose

     * restrictions on which thread can release a lock (typically only the

     * holder of the lock can release it) and may throw

     * an (unchecked) exception if the restriction is violated.

     * Any restrictions and the exception

     * type must be documented by that {@code Lock} implementation.

     */

    void unlock();

    /**

     * Returns a new {@link Condition} instance that is bound to this

     * {@code Lock} instance.

     *

     * <p>Before waiting on the condition the lock must be held by the

     * current thread.

     * A call to {@link Condition#await()} will atomically release the lock

     * before waiting and re-acquire the lock before the wait returns.

     *

     * <p><b>Implementation Considerations</b>

     *

     * <p>The exact operation of the {@link Condition} instance depends on

     * the {@code Lock} implementation and must be documented by that

     * implementation.

     *

     * @return A new {@link Condition} instance for this {@code Lock} instance

     * @throws UnsupportedOperationException if this {@code Lock}

     *         implementation does not support conditions

     */

    Condition newCondition();

}