jdk/src/share/classes/java/util/concurrent/locks/ReadWriteLock.java
author dl
Wed, 12 Jan 2011 14:40:36 +0000
changeset 7976 f273c0d04215
parent 5506 202f599c92aa
child 9242 ef138d47df58
permissions -rw-r--r--
7005424: Resync java.util.concurrent classes with Dougs CVS - Jan 2011 Reviewed-by: dholmes, chegar, mduigou
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     6
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     8
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    20
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
 * This file is available under and governed by the GNU General Public
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
 * License version 2 only, as published by the Free Software Foundation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
 * However, the following notice accompanied the original version of this
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
 * file:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * Written by Doug Lea with assistance from members of JCP JSR-166
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * Expert Group and released to the public domain, as explained at
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
 * http://creativecommons.org/licenses/publicdomain
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
package java.util.concurrent.locks;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * A <tt>ReadWriteLock</tt> maintains a pair of associated {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * Lock locks}, one for read-only operations and one for writing.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * The {@link #readLock read lock} may be held simultaneously by
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * multiple reader threads, so long as there are no writers.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * {@link #writeLock write lock} is exclusive.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * <p>All <tt>ReadWriteLock</tt> implementations must guarantee that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * the memory synchronization effects of <tt>writeLock</tt> operations
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * (as specified in the {@link Lock} interface) also hold with respect
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * to the associated <tt>readLock</tt>. That is, a thread successfully
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * acquiring the read lock will see all updates made upon previous
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 * release of the write lock.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * <p>A read-write lock allows for a greater level of concurrency in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * accessing shared data than that permitted by a mutual exclusion lock.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * It exploits the fact that while only a single thread at a time (a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * <em>writer</em> thread) can modify the shared data, in many cases any
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * number of threads can concurrently read the data (hence <em>reader</em>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * threads).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * In theory, the increase in concurrency permitted by the use of a read-write
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * lock will lead to performance improvements over the use of a mutual
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * exclusion lock. In practice this increase in concurrency will only be fully
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * realized on a multi-processor, and then only if the access patterns for
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * the shared data are suitable.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 * <p>Whether or not a read-write lock will improve performance over the use
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * of a mutual exclusion lock depends on the frequency that the data is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 * read compared to being modified, the duration of the read and write
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 * operations, and the contention for the data - that is, the number of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 * threads that will try to read or write the data at the same time.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
 * For example, a collection that is initially populated with data and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
 * thereafter infrequently modified, while being frequently searched
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
 * (such as a directory of some kind) is an ideal candidate for the use of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
 * a read-write lock. However, if updates become frequent then the data
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
 * spends most of its time being exclusively locked and there is little, if any
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
 * increase in concurrency. Further, if the read operations are too short
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
 * the overhead of the read-write lock implementation (which is inherently
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
 * more complex than a mutual exclusion lock) can dominate the execution
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
 * cost, particularly as many read-write lock implementations still serialize
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
 * all threads through a small section of code. Ultimately, only profiling
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
 * and measurement will establish whether the use of a read-write lock is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
 * suitable for your application.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
 * <p>Although the basic operation of a read-write lock is straight-forward,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
 * there are many policy decisions that an implementation must make, which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
 * may affect the effectiveness of the read-write lock in a given application.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
 * Examples of these policies include:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
 * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
 * <li>Determining whether to grant the read lock or the write lock, when
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
 * both readers and writers are waiting, at the time that a writer releases
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
 * the write lock. Writer preference is common, as writes are expected to be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
 * short and infrequent. Reader preference is less common as it can lead to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
 * lengthy delays for a write if the readers are frequent and long-lived as
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
 * expected. Fair, or &quot;in-order&quot; implementations are also possible.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
 * <li>Determining whether readers that request the read lock while a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
 * reader is active and a writer is waiting, are granted the read lock.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
 * Preference to the reader can delay the writer indefinitely, while
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
 * preference to the writer can reduce the potential for concurrency.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
 * <li>Determining whether the locks are reentrant: can a thread with the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
 * write lock reacquire it? Can it acquire a read lock while holding the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
 * write lock? Is the read lock itself reentrant?
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
 * <li>Can the write lock be downgraded to a read lock without allowing
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
 * an intervening writer? Can a read lock be upgraded to a write lock,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
 * in preference to other waiting readers or writers?
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
 * </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
 * You should consider all of these things when evaluating the suitability
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
 * of a given implementation for your application.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
 * @see ReentrantReadWriteLock
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
 * @see Lock
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
 * @see ReentrantLock
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
 * @since 1.5
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
 * @author Doug Lea
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
public interface ReadWriteLock {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
     * Returns the lock used for reading.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     * @return the lock used for reading.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
    Lock readLock();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
     * Returns the lock used for writing.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
     * @return the lock used for writing.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
    Lock writeLock();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
}