1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/locks/ReadWriteLock.java Sat Mar 19 10:46:31 2016 +0100
1.3 @@ -0,0 +1,133 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util.concurrent.locks;
1.40 +
1.41 +/**
1.42 + * A <tt>ReadWriteLock</tt> maintains a pair of associated {@link
1.43 + * Lock locks}, one for read-only operations and one for writing.
1.44 + * The {@link #readLock read lock} may be held simultaneously by
1.45 + * multiple reader threads, so long as there are no writers. The
1.46 + * {@link #writeLock write lock} is exclusive.
1.47 + *
1.48 + * <p>All <tt>ReadWriteLock</tt> implementations must guarantee that
1.49 + * the memory synchronization effects of <tt>writeLock</tt> operations
1.50 + * (as specified in the {@link Lock} interface) also hold with respect
1.51 + * to the associated <tt>readLock</tt>. That is, a thread successfully
1.52 + * acquiring the read lock will see all updates made upon previous
1.53 + * release of the write lock.
1.54 + *
1.55 + * <p>A read-write lock allows for a greater level of concurrency in
1.56 + * accessing shared data than that permitted by a mutual exclusion lock.
1.57 + * It exploits the fact that while only a single thread at a time (a
1.58 + * <em>writer</em> thread) can modify the shared data, in many cases any
1.59 + * number of threads can concurrently read the data (hence <em>reader</em>
1.60 + * threads).
1.61 + * In theory, the increase in concurrency permitted by the use of a read-write
1.62 + * lock will lead to performance improvements over the use of a mutual
1.63 + * exclusion lock. In practice this increase in concurrency will only be fully
1.64 + * realized on a multi-processor, and then only if the access patterns for
1.65 + * the shared data are suitable.
1.66 + *
1.67 + * <p>Whether or not a read-write lock will improve performance over the use
1.68 + * of a mutual exclusion lock depends on the frequency that the data is
1.69 + * read compared to being modified, the duration of the read and write
1.70 + * operations, and the contention for the data - that is, the number of
1.71 + * threads that will try to read or write the data at the same time.
1.72 + * For example, a collection that is initially populated with data and
1.73 + * thereafter infrequently modified, while being frequently searched
1.74 + * (such as a directory of some kind) is an ideal candidate for the use of
1.75 + * a read-write lock. However, if updates become frequent then the data
1.76 + * spends most of its time being exclusively locked and there is little, if any
1.77 + * increase in concurrency. Further, if the read operations are too short
1.78 + * the overhead of the read-write lock implementation (which is inherently
1.79 + * more complex than a mutual exclusion lock) can dominate the execution
1.80 + * cost, particularly as many read-write lock implementations still serialize
1.81 + * all threads through a small section of code. Ultimately, only profiling
1.82 + * and measurement will establish whether the use of a read-write lock is
1.83 + * suitable for your application.
1.84 + *
1.85 + *
1.86 + * <p>Although the basic operation of a read-write lock is straight-forward,
1.87 + * there are many policy decisions that an implementation must make, which
1.88 + * may affect the effectiveness of the read-write lock in a given application.
1.89 + * Examples of these policies include:
1.90 + * <ul>
1.91 + * <li>Determining whether to grant the read lock or the write lock, when
1.92 + * both readers and writers are waiting, at the time that a writer releases
1.93 + * the write lock. Writer preference is common, as writes are expected to be
1.94 + * short and infrequent. Reader preference is less common as it can lead to
1.95 + * lengthy delays for a write if the readers are frequent and long-lived as
1.96 + * expected. Fair, or "in-order" implementations are also possible.
1.97 + *
1.98 + * <li>Determining whether readers that request the read lock while a
1.99 + * reader is active and a writer is waiting, are granted the read lock.
1.100 + * Preference to the reader can delay the writer indefinitely, while
1.101 + * preference to the writer can reduce the potential for concurrency.
1.102 + *
1.103 + * <li>Determining whether the locks are reentrant: can a thread with the
1.104 + * write lock reacquire it? Can it acquire a read lock while holding the
1.105 + * write lock? Is the read lock itself reentrant?
1.106 + *
1.107 + * <li>Can the write lock be downgraded to a read lock without allowing
1.108 + * an intervening writer? Can a read lock be upgraded to a write lock,
1.109 + * in preference to other waiting readers or writers?
1.110 + *
1.111 + * </ul>
1.112 + * You should consider all of these things when evaluating the suitability
1.113 + * of a given implementation for your application.
1.114 + *
1.115 + * @see ReentrantReadWriteLock
1.116 + * @see Lock
1.117 + * @see ReentrantLock
1.118 + *
1.119 + * @since 1.5
1.120 + * @author Doug Lea
1.121 + */
1.122 +public interface ReadWriteLock {
1.123 + /**
1.124 + * Returns the lock used for reading.
1.125 + *
1.126 + * @return the lock used for reading.
1.127 + */
1.128 + Lock readLock();
1.129 +
1.130 + /**
1.131 + * Returns the lock used for writing.
1.132 + *
1.133 + * @return the lock used for writing.
1.134 + */
1.135 + Lock writeLock();
1.136 +}