util/concurrent/Locks.java

package java.util.concurrent;


/**
 * Utility operations for built-in synchronization and {@link Lock} classes.
 * <p>The <tt>Locks</tt> class defines utility methods that enhance the
 * use of <tt>synchronized</tt> methods and statements by:
 * <ul>
 * <li>allowing for an attempt to acquire a monitor lock only if it is free, 
 * or if it becomes free within a specified time;
 * <li>allowing an attempt to acquire a monitor lock to be interruptible; and
 * <li>providing a method to acquire multiple monitor locks only if
 * they are all available.
 * </ul>
 * <p>An additional convenience method is provided to acquire multiple
 * {@link Lock} instances only if they are all available.
 * <p>To preserve the block-structured locking that is required for the
 * built-in monitor locks, each method takes a {@link Runnable} action as 
 * an argument and executes its {@link Runnable#run run} method with the 
 * appropriate locks held. 
 * When the {@link Runnable#run run} method completes all locks
 * are released.
 *
 * <p><b>Note:</b> All methods that take {@link Object} parameters treat
 * those parameters as {@link Object Objects}, even if they happen to be
 * {@link Lock} instances. These methods will always acquire the monitor
 * lock of the given object - they will not perform a {@link Lock#lock}
 * invocation.
 *
 * <p>Except where noted, passing a <tt>null</tt> value for any parameter
 * will result in a {@link NullPointerException} being thrown.
 *
 * <h3>Memory Synchronization</h3>
 * <p>When a {@link Runnable} object's {@link Runnable#run run} method is 
 * executed it means that the appropriate 
 * lock (or locks) has been acquired, and so the memory synchronization 
 * effects of acquiring that lock will have taken place. Similarly, when
 * the {@link Runnable} object's {@link Runnable#run run} method completes,
 * the lock (or locks) is released and the associated memory synchronization
 * effects will take place. Exactly what those memory synchronization
 * effects are will depend on the nature of the lock and the type of 
 * acquisition/release - for example, reentrantly acquiring a monitor lock
 * has no associated memory synchronization effects.
 * <p>When mutliple locks are involved it may be that some of the locks are
 * acquired and subsequently released, before an unavailable lock is found.
 * In that case the memory synchronization effects will be those of the locks
 * that were actually acquired and actually released.
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/01/09 17:56:51 $
 * @editor $Author: dl $
 *
 * @fixme add implementation notes for any performance issues related to
 * timeouts or interrupts
 **/
public class Locks {

    private Locks() {} // uninstantiable.

    /**
     * Performs the given action holding the monitor lock of
     * the given object only if that lock is currently free.
     *
     * <p>If the monitor lock of the given object is immediately available
     * to the current thread then it is acquired. 
     * The action is then executed and finally the monitor lock is released
     * and the method returns with the value <tt>true</tt>.
     * <p>If the monitor lock is not available then the method returns 
     * immediately with the value <tt>false</tt>.
     * <p>If the action completes abruptly due to an {@link Error} or
     * {@link RuntimeException}, then the method completes abruptly
     * for the same reason, after the lock has been released.
     *
     * @param lock the object whose monitor lock must be acquired
     * @param action the code to run while holding the monitor lock
     * @return <tt>true</tt> if the action was executed, and <tt>false</tt>
     * otherwise.
     **/
    public static boolean attempt(Object lock, Runnable action) {
        return false; // for now;
    }

    /**
     * Performs the given action holding the monitor lock of
     * the given object if it is free within the given waiting time and the
     * current thread has not been {@link Thread#interrupt interrupted}.
     *
     * <p>If the monitor lock of the given object is immediately available
     * to the current thread then it is acquired. 
     * The action is then executed and finally the monitor lock is released
     * and the method returns with the value <tt>true</tt>.
     *
     * <p>If the monitor lock is not available then
     * the current thread becomes disabled for thread scheduling 
     * purposes and lies dormant until one of three things happens:
     * <ul>
     * <li> The monitor lock is acquired by the current thread; or
     * <li> Some other thread {@link Thread#interrupt interrupts} the current
     * thread; or
     * <li> The specified waiting time elapses
     * </ul>
     * <p>If the monitor lock is acquired
     * the action is executed then the monitor lock is released
     * and the method returns with the value <tt>true</tt>.
     *
     * <p>If the action completes abruptly due to an {@link Error} or
     * {@link RuntimeException}, then the method completes abruptly
     * for the same reason, after the lock has been released.
     *
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or 
     * <li>is {@link Thread#interrupt interrupted} while waiting to acquire 
     * the monitor lock, 
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's 
     * interrupted status is cleared. 
     *
     * <p>If the specified waiting time elapses then the value <tt>false</tt>
     * is returned.
     * The given waiting time is a best-effort lower bound. If the time is 
     * less than or equal to zero, the method will not wait at all.
     *
     * <p><b>Implementation Notes</b>
     * <p>TO-BE-DONE
     *
     *
     * @param lock the object whose monitor lock must be acquired
     * @param action the code to run while holding the monitor lock
     * @param timeout the maximum time to wait for the monitor lock
     * @param granularity the time unit of the <tt>timeout</tt> argument.
     * @return <tt>true</tt> if the monitor lock was acquired and the
     * action executed, and <tt>false</tt>
     * if the waiting time elapsed before the monitor lock was acquired.
     *
     * @throws InterruptedException if the current thread is interrupted
     * while trying to acquire the monitor lock.
     *
     * @see Thread#interrupt
     *
     **/
    public static boolean attempt(Object lock, Runnable action, 
                                  long timeout, TimeUnit granularity)
        throws InterruptedException {

        return false; // for now;
    }

    /**
     * Performs the given action holding the monitor locks of
     * the given objects only if those locks are currently free.
     *
     * <p>If the monitor locks of each object in the array are immediately 
     * available to the current thread then they are acquired. 
     * The action is then executed and finally the monitor locks are released
     * and the method returns with the value <tt>true</tt>.
     * <p>If any of the monitor locks is not available then 
     * all previously acquired monitor locks are released and the method 
     * returns with the value <tt>false</tt>.
     * <p>If the action completes abruptly due to an {@link Error} or
     * {@link RuntimeException}, then the method completes abruptly
     * for the same reason, after all the locks have been released.
     *
     * @param locks the objects whose monitor locks must be acquired
     * @param action the code to run while holding the monitor locks
     * @return <tt>true</tt> if the action was executed, and <tt>false</tt>
     * otherwise.
     *
     * @throws NullPointerException if an attempt is made to acquire the
     * monitor lock of a <tt>null</tt> element in the <tt>locks</tt> array.
     **/
    public static boolean attempt(Object[] locks, Runnable action) {
        return false; // for now;
    }

    /**
     * Performs the given action holding the given {@link Lock} instances, only
     * if those {@link Lock} instances are currently free.
     *
     * <p>If each of the locks in the array are immediately 
     * available to the current thread then they are acquired. 
     * The action is then executed and finally the locks are 
     * released and the method returns with the value <tt>true</tt>.
     * <p>If any of the locks are not available then 
     * all previously acquired locks are released and the 
     * method returns immediately with the value <tt>false</tt>.
     * <p>If the action completes abruptly due to an {@link Error} or
     * {@link RuntimeException}, then the method completes abruptly
     * for the same reason, after all the locks have been 
     * released.
     *
     * @param locks the {@link Lock} instances that must be acquired
     * @param action the code to run while holding the given locks
     * @return <tt>true</tt> if the action was executed, and <tt>false</tt>
     * otherwise.
     *
     * @throws NullPointerException if an attempt is made to acquire the
     * lock of a <tt>null</tt> element in the <tt>locks</tt> array.
     **/
    public static boolean attempt(Lock[] locks, Runnable action) {
        return false; // for now;
    }


    /**
     * Returns a {@link Condition} instance for use with the given object.
     * <p>The returned {@link Condition} instance has analagous behavior 
     * to the use of the monitor methods on the given object. Given
     * <pre>    Condition c = Locks.newConditionFor(o);
     * </pre>
     * then:
     * <ul>
     * <li><tt>c.await()</tt> is analagous to <tt>o.wait()</tt>
     * <li><tt>c.signal()</tt> is analagous to <tt>o.notify()</tt>; and
     * <li><tt>c.signalAll()</tt> is analagous to <tt>o.notifyAll()</tt>
     * </ul>
     * in that:
     * <ul>
     * <li>If the monitor lock of <tt>o</tt> is not held when any of the 
     * {@link Condition}
     * {@link Condition#await() waiting} or {@link Condition#signal signalling}
     * methods are called, then an {@link IllegalMonitorStateException} is
     * thrown.
     * <li>When the condition {@link Condition#await() waiting} methods are
     * called the monitor lock of <tt>o</tt> is released and before they 
     * return the monitor lock is
     * reacquired and the lock count restored to what it was when the
     * method was called.
     * <li>If a thread is {@link Thread#interrupt interrupted} while waiting
     * then the wait will terminate, an {@link InterruptedException} will be
     * thrown, and the thread's interrupted status will be cleared.
     * <li>The order in which waiting threads are signalled is not specified.
     * <li>The order in which threads returning from await, and threads trying
     * to acquire the monitor lock, are granted the lock, is not specified.
     * </ul>
     * <p>A {@link Condition} instance obtained in this way can be used to 
     * create the
     * affect of having additional monitor wait-sets for the given object.
     * For example, suppose we have a bounded buffer which supports methods
     * to <tt>put</tt> and <tt>take</tt> items in/from the buffer. If a 
     * <tt>take</tt> is attempted on an empty buffer then the thread will block
     * until an item becomes available; if a <tt>put</tt> is attempted on a
     * full buffer, then the thread will block until a space becomes available.
     * We would like to keep waiting <tt>put</tt> threads and <tt>take</tt>
     * threads in separate wait-sets so that we can use the optimisation of
     * only notifying a single thread at a time when items, or spaces, become
     * available in the buffer. This can be achieved using either two 
     * {@link Condition} instances, or one {@link Condition} instance and the 
     * actual
     * monitor wait-set. For clarity we'll use two {@link Condition} instances.
     * <pre><code>
     * class BoundedBuffer {
     *   <b>final Condition notFull  = Locks.newConditionFor(this); 
     *   final Condition notEmpty = Locks.newConditionFor(this); </b>
     *
     *   Object[] items = new Object[100];
     *   int putptr, takeptr, count;
     *
     *   public <b>synchronized</b> void put(Object x) 
     *                              throws InterruptedException {
     *     while (count == items.length) 
     *       <b>notFull.await();</b>
     *     items[putptr] = x; 
     *     if (++putptr == items.length) putptr = 0;
     *     ++count;
     *     <b>notEmpty.signal();</b>
     *   }
     *
     *   public <b>synchronized</b> Object take() throws InterruptedException {
     *     while (count == 0) 
     *       <b>notEmpty.await();</b>
     *     Object x = items[takeptr]; 
     *     if (++takeptr == items.length) takeptr = 0;
     *     --count;
     *     <b>notFull.signal();</b>
     *     return x;
     *   } 
     * }
     * </code></pre>
     *
     * @param lock the object that will be used for its monitor lock and to
     * which the returned condition should be bound.
     * @return a {@link Condition} instance bound to the given object
     **/
    public static Condition newConditionFor(Object lock) {
        return null; // for now;
    }

}


Revision:	1.1
Committed:	Wed May 14 21:30:47 2003 UTC (21 years ago) by tim
Branch:	MAIN
Log Message:	Moved main source rooted at . to ./src/main Moved test source rooted at ./etc/testcases to ./src/test
#	User	Rev	Content
1	tim	1.1	package java.util.concurrent;
2
3
4			/**
5			* Utility operations for built-in synchronization and {@link Lock} classes.
6			* <p>The <tt>Locks</tt> class defines utility methods that enhance the
7			* use of <tt>synchronized</tt> methods and statements by:
8			* <ul>
9			* <li>allowing for an attempt to acquire a monitor lock only if it is free,
10			* or if it becomes free within a specified time;
11			* <li>allowing an attempt to acquire a monitor lock to be interruptible; and
12			* <li>providing a method to acquire multiple monitor locks only if
13			* they are all available.
14			* </ul>
15			* <p>An additional convenience method is provided to acquire multiple
16			* {@link Lock} instances only if they are all available.
17			* <p>To preserve the block-structured locking that is required for the
18			* built-in monitor locks, each method takes a {@link Runnable} action as
19			* an argument and executes its {@link Runnable#run run} method with the
20			* appropriate locks held.
21			* When the {@link Runnable#run run} method completes all locks
22			* are released.
23			*
24			* <p><b>Note:</b> All methods that take {@link Object} parameters treat
25			* those parameters as {@link Object Objects}, even if they happen to be
26			* {@link Lock} instances. These methods will always acquire the monitor
27			* lock of the given object - they will not perform a {@link Lock#lock}
28			* invocation.
29			*
30			* <p>Except where noted, passing a <tt>null</tt> value for any parameter
31			* will result in a {@link NullPointerException} being thrown.
32			*
33			* <h3>Memory Synchronization</h3>
34			* <p>When a {@link Runnable} object's {@link Runnable#run run} method is
35			* executed it means that the appropriate
36			* lock (or locks) has been acquired, and so the memory synchronization
37			* effects of acquiring that lock will have taken place. Similarly, when
38			* the {@link Runnable} object's {@link Runnable#run run} method completes,
39			* the lock (or locks) is released and the associated memory synchronization
40			* effects will take place. Exactly what those memory synchronization
41			* effects are will depend on the nature of the lock and the type of
42			* acquisition/release - for example, reentrantly acquiring a monitor lock
43			* has no associated memory synchronization effects.
44			* <p>When mutliple locks are involved it may be that some of the locks are
45			* acquired and subsequently released, before an unavailable lock is found.
46			* In that case the memory synchronization effects will be those of the locks
47			* that were actually acquired and actually released.
48			*
49			* @since 1.5
50			* @spec JSR-166
51			* @revised $Date: 2003/01/09 17:56:51 $
52			* @editor $Author: dl $
53			*
54			* @fixme add implementation notes for any performance issues related to
55			* timeouts or interrupts
56			**/
57			public class Locks {
58
59			private Locks() {} // uninstantiable.
60
61			/**
62			* Performs the given action holding the monitor lock of
63			* the given object only if that lock is currently free.
64			*
65			* <p>If the monitor lock of the given object is immediately available
66			* to the current thread then it is acquired.
67			* The action is then executed and finally the monitor lock is released
68			* and the method returns with the value <tt>true</tt>.
69			* <p>If the monitor lock is not available then the method returns
70			* immediately with the value <tt>false</tt>.
71			* <p>If the action completes abruptly due to an {@link Error} or
72			* {@link RuntimeException}, then the method completes abruptly
73			* for the same reason, after the lock has been released.
74			*
75			* @param lock the object whose monitor lock must be acquired
76			* @param action the code to run while holding the monitor lock
77			* @return <tt>true</tt> if the action was executed, and <tt>false</tt>
78			* otherwise.
79			**/
80			public static boolean attempt(Object lock, Runnable action) {
81			return false; // for now;
82			}
83
84			/**
85			* Performs the given action holding the monitor lock of
86			* the given object if it is free within the given waiting time and the
87			* current thread has not been {@link Thread#interrupt interrupted}.
88			*
89			* <p>If the monitor lock of the given object is immediately available
90			* to the current thread then it is acquired.
91			* The action is then executed and finally the monitor lock is released
92			* and the method returns with the value <tt>true</tt>.
93			*
94			* <p>If the monitor lock is not available then
95			* the current thread becomes disabled for thread scheduling
96			* purposes and lies dormant until one of three things happens:
97			* <ul>
98			* <li> The monitor lock is acquired by the current thread; or
99			* <li> Some other thread {@link Thread#interrupt interrupts} the current
100			* thread; or
101			* <li> The specified waiting time elapses
102			* </ul>
103			* <p>If the monitor lock is acquired
104			* the action is executed then the monitor lock is released
105			* and the method returns with the value <tt>true</tt>.
106			*
107			* <p>If the action completes abruptly due to an {@link Error} or
108			* {@link RuntimeException}, then the method completes abruptly
109			* for the same reason, after the lock has been released.
110			*
111			* <p>If the current thread:
112			* <ul>
113			* <li>has its interrupted status set on entry to this method; or
114			* <li>is {@link Thread#interrupt interrupted} while waiting to acquire
115			* the monitor lock,
116			* </ul>
117			* then {@link InterruptedException} is thrown and the current thread's
118			* interrupted status is cleared.
119			*
120			* <p>If the specified waiting time elapses then the value <tt>false</tt>
121			* is returned.
122			* The given waiting time is a best-effort lower bound. If the time is
123			* less than or equal to zero, the method will not wait at all.
124			*
125			* <p><b>Implementation Notes</b>
126			* <p>TO-BE-DONE
127			*
128			*
129			* @param lock the object whose monitor lock must be acquired
130			* @param action the code to run while holding the monitor lock
131			* @param timeout the maximum time to wait for the monitor lock
132			* @param granularity the time unit of the <tt>timeout</tt> argument.
133			* @return <tt>true</tt> if the monitor lock was acquired and the
134			* action executed, and <tt>false</tt>
135			* if the waiting time elapsed before the monitor lock was acquired.
136			*
137			* @throws InterruptedException if the current thread is interrupted
138			* while trying to acquire the monitor lock.
139			*
140			* @see Thread#interrupt
141			*
142			**/
143			public static boolean attempt(Object lock, Runnable action,
144			long timeout, TimeUnit granularity)
145			throws InterruptedException {
146
147			return false; // for now;
148			}
149
150			/**
151			* Performs the given action holding the monitor locks of
152			* the given objects only if those locks are currently free.
153			*
154			* <p>If the monitor locks of each object in the array are immediately
155			* available to the current thread then they are acquired.
156			* The action is then executed and finally the monitor locks are released
157			* and the method returns with the value <tt>true</tt>.
158			* <p>If any of the monitor locks is not available then
159			* all previously acquired monitor locks are released and the method
160			* returns with the value <tt>false</tt>.
161			* <p>If the action completes abruptly due to an {@link Error} or
162			* {@link RuntimeException}, then the method completes abruptly
163			* for the same reason, after all the locks have been released.
164			*
165			* @param locks the objects whose monitor locks must be acquired
166			* @param action the code to run while holding the monitor locks
167			* @return <tt>true</tt> if the action was executed, and <tt>false</tt>
168			* otherwise.
169			*
170			* @throws NullPointerException if an attempt is made to acquire the
171			* monitor lock of a <tt>null</tt> element in the <tt>locks</tt> array.
172			**/
173			public static boolean attempt(Object[] locks, Runnable action) {
174			return false; // for now;
175			}
176
177			/**
178			* Performs the given action holding the given {@link Lock} instances, only
179			* if those {@link Lock} instances are currently free.
180			*
181			* <p>If each of the locks in the array are immediately
182			* available to the current thread then they are acquired.
183			* The action is then executed and finally the locks are
184			* released and the method returns with the value <tt>true</tt>.
185			* <p>If any of the locks are not available then
186			* all previously acquired locks are released and the
187			* method returns immediately with the value <tt>false</tt>.
188			* <p>If the action completes abruptly due to an {@link Error} or
189			* {@link RuntimeException}, then the method completes abruptly
190			* for the same reason, after all the locks have been
191			* released.
192			*
193			* @param locks the {@link Lock} instances that must be acquired
194			* @param action the code to run while holding the given locks
195			* @return <tt>true</tt> if the action was executed, and <tt>false</tt>
196			* otherwise.
197			*
198			* @throws NullPointerException if an attempt is made to acquire the
199			* lock of a <tt>null</tt> element in the <tt>locks</tt> array.
200			**/
201			public static boolean attempt(Lock[] locks, Runnable action) {
202			return false; // for now;
203			}
204
205
206			/**
207			* Returns a {@link Condition} instance for use with the given object.
208			* <p>The returned {@link Condition} instance has analagous behavior
209			* to the use of the monitor methods on the given object. Given
210			* <pre> Condition c = Locks.newConditionFor(o);
211			* </pre>
212			* then:
213			* <ul>
214			* <li><tt>c.await()</tt> is analagous to <tt>o.wait()</tt>
215			* <li><tt>c.signal()</tt> is analagous to <tt>o.notify()</tt>; and
216			* <li><tt>c.signalAll()</tt> is analagous to <tt>o.notifyAll()</tt>
217			* </ul>
218			* in that:
219			* <ul>
220			* <li>If the monitor lock of <tt>o</tt> is not held when any of the
221			* {@link Condition}
222			* {@link Condition#await() waiting} or {@link Condition#signal signalling}
223			* methods are called, then an {@link IllegalMonitorStateException} is
224			* thrown.
225			* <li>When the condition {@link Condition#await() waiting} methods are
226			* called the monitor lock of <tt>o</tt> is released and before they
227			* return the monitor lock is
228			* reacquired and the lock count restored to what it was when the
229			* method was called.
230			* <li>If a thread is {@link Thread#interrupt interrupted} while waiting
231			* then the wait will terminate, an {@link InterruptedException} will be
232			* thrown, and the thread's interrupted status will be cleared.
233			* <li>The order in which waiting threads are signalled is not specified.
234			* <li>The order in which threads returning from await, and threads trying
235			* to acquire the monitor lock, are granted the lock, is not specified.
236			* </ul>
237			* <p>A {@link Condition} instance obtained in this way can be used to
238			* create the
239			* affect of having additional monitor wait-sets for the given object.
240			* For example, suppose we have a bounded buffer which supports methods
241			* to <tt>put</tt> and <tt>take</tt> items in/from the buffer. If a
242			* <tt>take</tt> is attempted on an empty buffer then the thread will block
243			* until an item becomes available; if a <tt>put</tt> is attempted on a
244			* full buffer, then the thread will block until a space becomes available.
245			* We would like to keep waiting <tt>put</tt> threads and <tt>take</tt>
246			* threads in separate wait-sets so that we can use the optimisation of
247			* only notifying a single thread at a time when items, or spaces, become
248			* available in the buffer. This can be achieved using either two
249			* {@link Condition} instances, or one {@link Condition} instance and the
250			* actual
251			* monitor wait-set. For clarity we'll use two {@link Condition} instances.
252			* <pre><code>
253			* class BoundedBuffer {
254			* <b>final Condition notFull = Locks.newConditionFor(this);
255			* final Condition notEmpty = Locks.newConditionFor(this); </b>
256			*
257			* Object[] items = new Object[100];
258			* int putptr, takeptr, count;
259			*
260			* public <b>synchronized</b> void put(Object x)
261			* throws InterruptedException {
262			* while (count == items.length)
263			* <b>notFull.await();</b>
264			* items[putptr] = x;
265			* if (++putptr == items.length) putptr = 0;
266			* ++count;
267			* <b>notEmpty.signal();</b>
268			* }
269			*
270			* public <b>synchronized</b> Object take() throws InterruptedException {
271			* while (count == 0)
272			* <b>notEmpty.await();</b>
273			* Object x = items[takeptr];
274			* if (++takeptr == items.length) takeptr = 0;
275			* --count;
276			* <b>notFull.signal();</b>
277			* return x;
278			* }
279			* }
280			* </code></pre>
281			*
282			* @param lock the object that will be used for its monitor lock and to
283			* which the returned condition should be bound.
284			* @return a {@link Condition} instance bound to the given object
285			**/
286			public static Condition newConditionFor(Object lock) {
287			return null; // for now;
288			}
289
290			}
291
292
293
294