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
#	Content
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	}