concurrent/locks/ReadWriteLock.java

/*
 * 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/publicdomain/zero/1.0/
 */

package java.util.concurrent.locks;

/**
 * A {@code ReadWriteLock} maintains a pair of associated {@link
 * Lock locks}, one for read-only operations and one for writing.
 * The {@linkplain #readLock read lock} may be held simultaneously
 * by multiple reader threads, so long as there are no writers.
 * The {@linkplain #writeLock write lock} is exclusive.
 *
 * <p>All {@code ReadWriteLock} implementations must guarantee that
 * the memory synchronization effects of {@code writeLock} operations
 * (as specified in the {@link Lock} interface) also hold with respect
 * to the associated {@code readLock}. That is, a thread successfully
 * acquiring the read lock will see all updates made upon previous
 * release of the write lock.
 *
 * <p>A read-write lock allows for a greater level of concurrency in
 * accessing shared data than that permitted by a mutual exclusion lock.
 * It exploits the fact that while only a single thread at a time (a
 * <em>writer</em> thread) can modify the shared data, in many cases any
 * number of threads can concurrently read the data (hence <em>reader</em>
 * threads).
 * In theory, the increase in concurrency permitted by the use of a read-write
 * lock will lead to performance improvements over the use of a mutual
 * exclusion lock. In practice this increase in concurrency will only be fully
 * realized on a multi-processor, and then only if the access patterns for
 * the shared data are suitable.
 *
 * <p>Whether or not a read-write lock will improve performance over the use
 * of a mutual exclusion lock depends on the frequency that the data is
 * read compared to being modified, the duration of the read and write
 * operations, and the contention for the data - that is, the number of
 * threads that will try to read or write the data at the same time.
 * For example, a collection that is initially populated with data and
 * thereafter infrequently modified, while being frequently searched
 * (such as a directory of some kind) is an ideal candidate for the use of
 * a read-write lock. However, if updates become frequent then the data
 * spends most of its time being exclusively locked and there is little, if any
 * increase in concurrency. Further, if the read operations are too short
 * the overhead of the read-write lock implementation (which is inherently
 * more complex than a mutual exclusion lock) can dominate the execution
 * cost, particularly as many read-write lock implementations still serialize
 * all threads through a small section of code. Ultimately, only profiling
 * and measurement will establish whether the use of a read-write lock is
 * suitable for your application.
 *
 * <p>Although the basic operation of a read-write lock is straight-forward,
 * there are many policy decisions that an implementation must make, which
 * may affect the effectiveness of the read-write lock in a given application.
 * Examples of these policies include:
 * <ul>
 * <li>Determining whether to grant the read lock or the write lock, when
 * both readers and writers are waiting, at the time that a writer releases
 * the write lock. Writer preference is common, as writes are expected to be
 * short and infrequent. Reader preference is less common as it can lead to
 * lengthy delays for a write if the readers are frequent and long-lived as
 * expected. Fair, or &quot;in-order&quot; implementations are also possible.
 *
 * <li>Determining whether readers that request the read lock while a
 * reader is active and a writer is waiting, are granted the read lock.
 * Preference to the reader can delay the writer indefinitely, while
 * preference to the writer can reduce the potential for concurrency.
 *
 * <li>Determining whether the locks are reentrant: can a thread with the
 * write lock reacquire it? Can it acquire a read lock while holding the
 * write lock? Is the read lock itself reentrant?
 *
 * <li>Can the write lock be downgraded to a read lock without allowing
 * an intervening writer? Can a read lock be upgraded to a write lock,
 * in preference to other waiting readers or writers?
 *
 * </ul>
 * You should consider all of these things when evaluating the suitability
 * of a given implementation for your application.
 *
 * @see ReentrantReadWriteLock
 * @see Lock
 * @see ReentrantLock
 *
 * @since 1.5
 * @author Doug Lea
 */
public interface ReadWriteLock {
    /**
     * Returns the lock used for reading.
     *
     * @return the lock used for reading
     */
    Lock readLock();

    /**
     * Returns the lock used for writing.
     *
     * @return the lock used for writing
     */
    Lock writeLock();
}
Revision:	1.2
Committed:	Fri Jul 8 20:02:54 2016 UTC (7 years, 10 months ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+0 -1 lines
Log Message:	whitespace
#	User	Rev	Content
1	jsr166	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain, as explained at
4			* http://creativecommons.org/publicdomain/zero/1.0/
5			*/
6
7			package java.util.concurrent.locks;
8
9			/**
10			* A {@code ReadWriteLock} maintains a pair of associated {@link
11			* Lock locks}, one for read-only operations and one for writing.
12			* The {@linkplain #readLock read lock} may be held simultaneously
13			* by multiple reader threads, so long as there are no writers.
14			* The {@linkplain #writeLock write lock} is exclusive.
15			*
16			* <p>All {@code ReadWriteLock} implementations must guarantee that
17			* the memory synchronization effects of {@code writeLock} operations
18			* (as specified in the {@link Lock} interface) also hold with respect
19			* to the associated {@code readLock}. That is, a thread successfully
20			* acquiring the read lock will see all updates made upon previous
21			* release of the write lock.
22			*
23			* <p>A read-write lock allows for a greater level of concurrency in
24			* accessing shared data than that permitted by a mutual exclusion lock.
25			* It exploits the fact that while only a single thread at a time (a
26			* <em>writer</em> thread) can modify the shared data, in many cases any
27			* number of threads can concurrently read the data (hence <em>reader</em>
28			* threads).
29			* In theory, the increase in concurrency permitted by the use of a read-write
30			* lock will lead to performance improvements over the use of a mutual
31			* exclusion lock. In practice this increase in concurrency will only be fully
32			* realized on a multi-processor, and then only if the access patterns for
33			* the shared data are suitable.
34			*
35			* <p>Whether or not a read-write lock will improve performance over the use
36			* of a mutual exclusion lock depends on the frequency that the data is
37			* read compared to being modified, the duration of the read and write
38			* operations, and the contention for the data - that is, the number of
39			* threads that will try to read or write the data at the same time.
40			* For example, a collection that is initially populated with data and
41			* thereafter infrequently modified, while being frequently searched
42			* (such as a directory of some kind) is an ideal candidate for the use of
43			* a read-write lock. However, if updates become frequent then the data
44			* spends most of its time being exclusively locked and there is little, if any
45			* increase in concurrency. Further, if the read operations are too short
46			* the overhead of the read-write lock implementation (which is inherently
47			* more complex than a mutual exclusion lock) can dominate the execution
48			* cost, particularly as many read-write lock implementations still serialize
49			* all threads through a small section of code. Ultimately, only profiling
50			* and measurement will establish whether the use of a read-write lock is
51			* suitable for your application.
52			*
53			* <p>Although the basic operation of a read-write lock is straight-forward,
54			* there are many policy decisions that an implementation must make, which
55			* may affect the effectiveness of the read-write lock in a given application.
56			* Examples of these policies include:
57			* <ul>
58			* <li>Determining whether to grant the read lock or the write lock, when
59			* both readers and writers are waiting, at the time that a writer releases
60			* the write lock. Writer preference is common, as writes are expected to be
61			* short and infrequent. Reader preference is less common as it can lead to
62			* lengthy delays for a write if the readers are frequent and long-lived as
63			* expected. Fair, or "in-order" implementations are also possible.
64			*
65			* <li>Determining whether readers that request the read lock while a
66			* reader is active and a writer is waiting, are granted the read lock.
67			* Preference to the reader can delay the writer indefinitely, while
68			* preference to the writer can reduce the potential for concurrency.
69			*
70			* <li>Determining whether the locks are reentrant: can a thread with the
71			* write lock reacquire it? Can it acquire a read lock while holding the
72			* write lock? Is the read lock itself reentrant?
73			*
74			* <li>Can the write lock be downgraded to a read lock without allowing
75			* an intervening writer? Can a read lock be upgraded to a write lock,
76			* in preference to other waiting readers or writers?
77			*
78			* </ul>
79			* You should consider all of these things when evaluating the suitability
80			* of a given implementation for your application.
81			*
82			* @see ReentrantReadWriteLock
83			* @see Lock
84			* @see ReentrantLock
85			*
86			* @since 1.5
87			* @author Doug Lea
88			*/
89			public interface ReadWriteLock {
90			/**
91			* Returns the lock used for reading.
92			*
93			* @return the lock used for reading
94			*/
95			Lock readLock();
96
97			/**
98			* Returns the lock used for writing.
99			*
100			* @return the lock used for writing
101			*/
102			Lock writeLock();
103			}