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