sample/java.util.concurrent.locks.ReadWriteLock.txt

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