01: /*
02: * The contents of this file are subject to the Sapient Public License
03: * Version 1.0 (the "License"); you may not use this file except in compliance
04: * with the License. You may obtain a copy of the License at
05: * http://carbon.sf.net/License.html.
06: *
07: * Software distributed under the License is distributed on an "AS IS" basis,
08: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
09: * the specific language governing rights and limitations under the License.
10: *
11: * The Original Code is The Carbon Component Framework.
12: *
13: * The Initial Developer of the Original Code is Sapient Corporation
14: *
15: * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16: */
17:
18: package org.sape.carbon.core.util.thread;
19:
20: /*
21: File: ReadWriteLock.java
22:
23: Originally written by Doug Lea and released into the public domain.
24: This may be used for any purposes whatsoever without acknowledgment.
25: Thanks for the assistance and support of Sun Microsystems Labs,
26: and everyone contributing, testing, and using this code.
27:
28: History:
29: Date Who What
30: 11Jun1998 dl Create public version
31: */
32:
33: /**
34: * ReadWriteLocks maintain a pair of associated locks.
35: * The readLock may be held simultanously by multiple
36: * reader threads, so long as there are no writers. The writeLock
37: * is exclusive. ReadWrite locks are generally preferable to
38: * plain Sync locks or synchronized methods in cases where:
39: * <ul>
40: * <li> The methods in a class can be cleanly separated into
41: * those that only access (read) data vs those that
42: * modify (write).
43: * <li> Target applications generally have more readers than writers.
44: * <li> The methods are relatively time-consuming (as a rough
45: * rule of thumb, exceed more than a hundred instructions), so it
46: * pays to introduce a bit more overhead associated with
47: * ReadWrite locks compared to simple synchronized methods etc
48: * in order to allow concurrency among reader threads.
49: *
50: * </ul>
51: * Different implementation classes differ in policies surrounding
52: * which threads to prefer when there is
53: * contention. By far, the most commonly useful policy is
54: * WriterPreferenceReadWriteLock. The other implementations
55: * are targeted for less common, niche applications.
56: *<p>
57: * Standard usage:
58: * <pre>
59: * class X {
60: * ReadWriteLock rw;
61: * // ...
62: *
63: * public void read() throws InterruptedException {
64: * rw.readLock().acquire();
65: * try {
66: * // ... do the read
67: * }
68: * finally {
69: * rw.readlock().release()
70: * }
71: * }
72: *
73: *
74: * public void write() throws InterruptedException {
75: * rw.writeLock().acquire();
76: * try {
77: * // ... do the write
78: * }
79: * finally {
80: * rw.writelock().release()
81: * }
82: * }
83: * }
84: * </pre>
85: * <p>[<a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>]
86: *
87: * @since carbon 2.0
88: * @author Greg Hinkle, March 2003
89: * @version $Revision: 1.3 $($Author: dvoet $ / $Date: 2003/05/05 21:21:24 $)
90: **/
91: public interface ReadWriteLock {
92: /** get the readLock **/
93: Sync readLock();
94:
95: /** get the writeLock **/
96: Sync writeLock();
97: }
|