util/concurrent/ReadWriteLock.java

package java.util.concurrent;

/**
 * A <tt>ReadWriteLock</tt> maintains a pair of associated 
 * {@link Locks locks}. 
 * 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/02/07 00:24:38 $
 * @editor $Author: dholmes $

 */
public interface ReadWriteLock {
    /**
     * Return the lock used for reading.
     **/
    public Lock readLock();

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