J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 3 | * |
| 4 | * This code is free software; you can redistribute it and/or modify it |
| 5 | * under the terms of the GNU General Public License version 2 only, as |
| 6 | * published by the Free Software Foundation. Sun designates this |
| 7 | * particular file as subject to the "Classpath" exception as provided |
| 8 | * by Sun in the LICENSE file that accompanied this code. |
| 9 | * |
| 10 | * This code is distributed in the hope that it will be useful, but WITHOUT |
| 11 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 12 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 13 | * version 2 for more details (a copy is included in the LICENSE file that |
| 14 | * accompanied this code). |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License version |
| 17 | * 2 along with this work; if not, write to the Free Software Foundation, |
| 18 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 19 | * |
| 20 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 21 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 22 | * have any questions. |
| 23 | */ |
| 24 | |
| 25 | /* |
| 26 | * This file is available under and governed by the GNU General Public |
| 27 | * License version 2 only, as published by the Free Software Foundation. |
| 28 | * However, the following notice accompanied the original version of this |
| 29 | * file: |
| 30 | * |
| 31 | * Written by Doug Lea with assistance from members of JCP JSR-166 |
| 32 | * Expert Group and released to the public domain, as explained at |
| 33 | * http://creativecommons.org/licenses/publicdomain |
| 34 | */ |
| 35 | |
| 36 | package java.util.concurrent.locks; |
| 37 | |
| 38 | /** |
| 39 | * A <tt>ReadWriteLock</tt> maintains a pair of associated {@link |
| 40 | * Lock locks}, one for read-only operations and one for writing. |
| 41 | * The {@link #readLock read lock} may be held simultaneously by |
| 42 | * multiple reader threads, so long as there are no writers. The |
| 43 | * {@link #writeLock write lock} is exclusive. |
| 44 | * |
| 45 | * <p>All <tt>ReadWriteLock</tt> implementations must guarantee that |
| 46 | * the memory synchronization effects of <tt>writeLock</tt> operations |
| 47 | * (as specified in the {@link Lock} interface) also hold with respect |
| 48 | * to the associated <tt>readLock</tt>. That is, a thread successfully |
| 49 | * acquiring the read lock will see all updates made upon previous |
| 50 | * release of the write lock. |
| 51 | * |
| 52 | * <p>A read-write lock allows for a greater level of concurrency in |
| 53 | * accessing shared data than that permitted by a mutual exclusion lock. |
| 54 | * It exploits the fact that while only a single thread at a time (a |
| 55 | * <em>writer</em> thread) can modify the shared data, in many cases any |
| 56 | * number of threads can concurrently read the data (hence <em>reader</em> |
| 57 | * threads). |
| 58 | * In theory, the increase in concurrency permitted by the use of a read-write |
| 59 | * lock will lead to performance improvements over the use of a mutual |
| 60 | * exclusion lock. In practice this increase in concurrency will only be fully |
| 61 | * realized on a multi-processor, and then only if the access patterns for |
| 62 | * the shared data are suitable. |
| 63 | * |
| 64 | * <p>Whether or not a read-write lock will improve performance over the use |
| 65 | * of a mutual exclusion lock depends on the frequency that the data is |
| 66 | * read compared to being modified, the duration of the read and write |
| 67 | * operations, and the contention for the data - that is, the number of |
| 68 | * threads that will try to read or write the data at the same time. |
| 69 | * For example, a collection that is initially populated with data and |
| 70 | * thereafter infrequently modified, while being frequently searched |
| 71 | * (such as a directory of some kind) is an ideal candidate for the use of |
| 72 | * a read-write lock. However, if updates become frequent then the data |
| 73 | * spends most of its time being exclusively locked and there is little, if any |
| 74 | * increase in concurrency. Further, if the read operations are too short |
| 75 | * the overhead of the read-write lock implementation (which is inherently |
| 76 | * more complex than a mutual exclusion lock) can dominate the execution |
| 77 | * cost, particularly as many read-write lock implementations still serialize |
| 78 | * all threads through a small section of code. Ultimately, only profiling |
| 79 | * and measurement will establish whether the use of a read-write lock is |
| 80 | * suitable for your application. |
| 81 | * |
| 82 | * |
| 83 | * <p>Although the basic operation of a read-write lock is straight-forward, |
| 84 | * there are many policy decisions that an implementation must make, which |
| 85 | * may affect the effectiveness of the read-write lock in a given application. |
| 86 | * Examples of these policies include: |
| 87 | * <ul> |
| 88 | * <li>Determining whether to grant the read lock or the write lock, when |
| 89 | * both readers and writers are waiting, at the time that a writer releases |
| 90 | * the write lock. Writer preference is common, as writes are expected to be |
| 91 | * short and infrequent. Reader preference is less common as it can lead to |
| 92 | * lengthy delays for a write if the readers are frequent and long-lived as |
| 93 | * expected. Fair, or "in-order" implementations are also possible. |
| 94 | * |
| 95 | * <li>Determining whether readers that request the read lock while a |
| 96 | * reader is active and a writer is waiting, are granted the read lock. |
| 97 | * Preference to the reader can delay the writer indefinitely, while |
| 98 | * preference to the writer can reduce the potential for concurrency. |
| 99 | * |
| 100 | * <li>Determining whether the locks are reentrant: can a thread with the |
| 101 | * write lock reacquire it? Can it acquire a read lock while holding the |
| 102 | * write lock? Is the read lock itself reentrant? |
| 103 | * |
| 104 | * <li>Can the write lock be downgraded to a read lock without allowing |
| 105 | * an intervening writer? Can a read lock be upgraded to a write lock, |
| 106 | * in preference to other waiting readers or writers? |
| 107 | * |
| 108 | * </ul> |
| 109 | * You should consider all of these things when evaluating the suitability |
| 110 | * of a given implementation for your application. |
| 111 | * |
| 112 | * @see ReentrantReadWriteLock |
| 113 | * @see Lock |
| 114 | * @see ReentrantLock |
| 115 | * |
| 116 | * @since 1.5 |
| 117 | * @author Doug Lea |
| 118 | */ |
| 119 | public interface ReadWriteLock { |
| 120 | /** |
| 121 | * Returns the lock used for reading. |
| 122 | * |
| 123 | * @return the lock used for reading. |
| 124 | */ |
| 125 | Lock readLock(); |
| 126 | |
| 127 | /** |
| 128 | * Returns the lock used for writing. |
| 129 | * |
| 130 | * @return the lock used for writing. |
| 131 | */ |
| 132 | Lock writeLock(); |
| 133 | } |