util/concurrent/ReadWriteLock.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;

/**
 * A <tt>ReadWriteLock</tt> maintains a pair of associated {@link
 * Locks locks}, one for read-only operations and one for writing.
 * The {@link #readLock read lock} may be held simultaneously by
 * multiple reader threads, so long as there are no writers.  The
 * {@link #writeLock write lock} is exclusive.
 * 
 * <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, whilst 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 write 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
 * @spec JSR-166
 * @revised $Date: 2003/06/07 18:20:21 $
 * @editor $Author: dl $
 * @author Doug Lea
 */
public interface ReadWriteLock {
    /**
     * Return the lock used for reading.
     **/
    Lock readLock();

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