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/24 14:34:48 $
 * @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.5
Committed:	Tue Jul 8 00:46:34 2003 UTC (20 years, 10 months ago) by dl
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.4:	+1 -1 lines
State:	*FILE REMOVED*
Log Message:	Locks in subpackage; fairness params added
#	Content
1	/*
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	package java.util.concurrent;
8
9	/**
10	* 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	*
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	* @revised $Date: 2003/06/24 14:34:48 $
83	* @editor $Author: dl $
84	* @author Doug Lea
85	*/
86	public interface ReadWriteLock {
87	/**
88	* Return the lock used for reading.
89	**/
90	Lock readLock();
91
92	/**
93	* Return the lock used for writing.
94	**/
95	Lock writeLock();
96	}