util/concurrent/ReentrantLock.java

package java.util.concurrent;

/**
 * A reentrant mutual exclusion lock.  
 * <p><tt>ReentrantLock</tt> defines a stand-alone {@link Lock} class with 
 * the same basic behavior and semantics as the implicit
 * monitor lock accessed by the use of <tt>synchronized</tt> methods and
 * statements, but without the forced block-structured locking and unlocking
 * that occurs with <tt>synchronized</tt> methods and
 * statements. 
 * In a good implementation the performance characteristics of using a
 * <tt>ReentrantLock</tt> instance should be about the same as using 
 * monitors directly.
 *
 * <p><em>Only</em> use this class when you want normal locking semantics but
 * need to use the lock in a non-nested fashion.
 *
 * <p>The order in which blocked threads are granted the lock is not
 * specified.
 *
 * <p>If you want a non-reentrant mutual exclusion lock then it is a simple
 * matter to use a reentrant lock in a non-reentrant way by ensuring that
 * the lock is not held by the current thread prior to locking.
 * See {@link #getHoldCount} for a way to check this.
 *
 *
 * <p><code>ReentrantLock</code> instances are intended to be used primarily 
 * in before/after constructions such as:
 *
 * <pre>
 * class X {
 *   ReentrantLock lock;
 *   // ...
 *
 *   public void m() { 
 *     lock.lock();  // block until condition holds
 *     try {
 *       // ... method body
 *     } finally {
 *       lock.unlock()
 *     }
 *   }
 * }
 * </pre>
 *
 * <p>This class supports the interruption of lock acquisition and provides a 
 * {@link #newCondition Condition} implementation that supports the 
 * interruption of thread suspension.
 *
 * <p>Except where noted, passing a <tt>null</tt> value for any parameter 
 * will result in a {@link NullPointerException} being thrown.
 *
 * <h3>Implentation Notes</h3>
 * <p> To-BE_DONE
 *
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/02/06 06:41:13 $
 * @editor $Author: dholmes $
 * 
 * @fixme (1) We need a non-nested example to motivate this
 * @fixme (2) Describe performance aspects of interruptible locking for the RI
 **/
public class ReentrantLock implements Lock {

    /**
     * Creates an instance of <tt>ReentrantLock</tt>
     */
    public ReentrantLock() {}

    /**
     * Acquirea the lock. 
     * <p>Acquires the lock if it is not held be another thread and returns 
     * immediately, setting the lock hold count to one.
     * <p>If the current thread
     * already holds the lock then the hold count is incremented by one and
     * the method returns immediately.
     * <p>If the lock is held by another thread then the
     * the current thread thread becomes disabled for thread scheduling 
     * purposes and lies dormant until the lock has been acquired
     * at which time the lock hold count is set to one. 
     */
    public void lock() {}

    /**
     * Acquires the lock unless the current thread is 
     * {@link Thread#interrupt interrupted}.
     * <p>Acquires the lock if it is not held by another thread and returns 
     * immediately, setting the lock hold count to one.
     * <p>If the current thread already holds this lock then the hold count 
     * is incremented by one and the method returns immediately.
     * <p>If the lock is held by another thread then the
     * the current thread becomes disabled for thread scheduling 
     * purposes and lies dormant until one of two things happens:
     * <ul>
     * <li> The lock is acquired by the current thread; or
     * <li> Some other thread {@link Thread#interrupt interrupts} the current
     * thread.
     * </ul>
     * <p>If the lock is acquired by the current thread then the lock hold 
     * count is set to one.
     * <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 lock,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's 
     * interrupted status is cleared. As this method is an explicit
     * interruption point, preference is given to responding to the interrupt
     * over reentrant acquisition of the lock.
     *
     * <h3>Implentation Notes</h3>
     * <p> To-BE_DONE
     *
     * @throws InterruptedException if the current thread is interrupted
     */
    public void lockInterruptibly() throws InterruptedException { }

    /**
     * Acquires the lock only if it is not held by another thread at the time
     * of invocation.
     * <p>Acquires the lock if it is not held by another thread and returns 
     * immediately with the value <tt>true</tt>, setting the lock hold count 
     * to one.
     * <p> If the current thread
     * already holds this lock then the hold count is incremented by one and
     * the method returns <tt>true</code>.
     * <p>If the lock is held by another thread then this method will return 
     * immediately with the value <tt>false</tt>.
     *
     * @return <tt>true</tt>if the lock was free and was acquired by the
     * current thread, or the lock was already held by the current thread; and
     * <tt>false</tt> otherwise.
     */
    public boolean tryLock() {
        return false;
    }

    /**
     *
     * Acquires the lock if it is not held by another thread  within the given 
     * waiting time and the current thread has not been interrupted. 
     * <p>Acquires the lock if it is not held by another thread and returns 
     * immediately with the value <tt>true</tt>, setting the lock hold count 
     * to one.
     * <p> If the current thread
     * already holds this lock then the hold count is incremented by one and
     * the method returns <tt>true</code>.
     * <p>If the lock is held by another thread then the
     * the current thread becomes disabled for thread scheduling 
     * purposes and lies dormant until one of three things happens:
     * <ul>
     * <li> The 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 lock is acquired then the value <tt>true</tt> is returned and
     * the lock hold count is set to one.
     * <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 lock,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's 
     * interrupted status is cleared. As this method is an explicit
     * interruption point, preference is given to responding to the interrupt
     * over reentrant acquisition of the lock.
     * <p>If the specified waiting time elapses then the value <tt>false</tt>
     * is returned.
     * <p>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.
     *
     * <h3>Implentation Notes</h3>
     * <p> To-BE_DONE
     *
     * @return <tt>true</tt> if the lock was free and was acquired by the
     * current thread, or the lock was already held by the current thread; and
     * <tt>false</tt> if the waiting time elapsed before the lock could be 
     * acquired.
     *
     * @throws InterruptedException if the current thread is interrupted
     */
    public boolean tryLock(long timeout, TimeUnit granularity) throws InterruptedException {
        return false;
    }

    /**
     * Attempts to release this lock.
     * <p>If the current thread is the holder of this lock then the hold count
     * is decremented. If the hold count is now zero then the lock is released.
     * <p>If the current thread is not the holder of this lock then
     * {@link IllegalMonitorStateException} is thrown.
     * @throws IllegalMonitorStateExeception if the current thread does not
     * hold this lock.
     */
    public void unlock() {}

    /**
     * Queries the number of holds on this lock by the current thread.
     * <p>A thread has a hold on a lock for each lock action that is not 
     * matched by an unlock action.
     * <p>The hold count information is typically only used for testing and
     * debugging purposes. For example, if a certain section of code should
     * not be entered with the lock already held then we can assert that
     * fact:
     * <pre>
     * class X {
     *   ReentrantLock lock = new ReentrantLock();
     *   // ...
     *
     *   public void m() { 
     *     assert lock.getHoldCount() == 0;
     *     lock.lock();
     *     try {
     *       // ... method body
     *     } finally {
     *       lock.unlock()
     *     }
     *   }
     * }
     * </pre>
     *
     * @return the number of holds on this lock by current thread,
     * or zero if this lock is not held by current thread.
     **/
    public int getHoldCount() {
        return 0;
    }

    /**
     * Queries if this lock is held by the current thread.
     * <p>Analogous to the {@link Thread#holdsLock} method for built-in
     * monitor locks, this method is typically used for debugging and
     * testing. For example, a method that should only be called while
     * a lock is held can assert that this is the case:
     * <pre>
     * class X {
     *   ReentrantLock lock = new ReentrantLock();
     *   // ...
     *
     *   public void m() { 
     *       assert lock.isHeldByCurrentThread();
     *       // ... method body
     *   }
     * }
     * </pre>
     *
     * @return <tt>true</tt> if current thread holds this lock and 
     * <tt>false</tt> otherwise.
     **/
    public boolean isHeldByCurrentThread() {
        return false;
    }

    /**
     * Returns a {@link Condition} instance for use with this 
     * {@link Lock} instance.
     *
     * <p>The returned {@link Condition} instance has the same behavior and 
     * usage
     * restrictions with this lock as the {@link Object} monitor methods
     * ({@link Object#wait() wait}, {@link Object#notify notify}, and
     * {@link Object#notifyAll notifyAll}) have with the built-in monitor
     * lock:
     * <ul>
     * <li>If this lock 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 lock is released and before they return the lock is
     * reacquired and the lock hold 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 a wait, and threads trying
     * to acquire the lock, are granted the lock, is not specified.
     * </ul>
     */
    public Condition newCondition() {
        return null;
    }

}


Revision:	1.1
Committed:	Wed May 14 21:30:47 2003 UTC (21 years, 1 month 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			* A reentrant mutual exclusion lock.
5			* <p><tt>ReentrantLock</tt> defines a stand-alone {@link Lock} class with
6			* the same basic behavior and semantics as the implicit
7			* monitor lock accessed by the use of <tt>synchronized</tt> methods and
8			* statements, but without the forced block-structured locking and unlocking
9			* that occurs with <tt>synchronized</tt> methods and
10			* statements.
11			* In a good implementation the performance characteristics of using a
12			* <tt>ReentrantLock</tt> instance should be about the same as using
13			* monitors directly.
14			*
15			* <p><em>Only</em> use this class when you want normal locking semantics but
16			* need to use the lock in a non-nested fashion.
17			*
18			* <p>The order in which blocked threads are granted the lock is not
19			* specified.
20			*
21			* <p>If you want a non-reentrant mutual exclusion lock then it is a simple
22			* matter to use a reentrant lock in a non-reentrant way by ensuring that
23			* the lock is not held by the current thread prior to locking.
24			* See {@link #getHoldCount} for a way to check this.
25			*
26			*
27			* <p><code>ReentrantLock</code> instances are intended to be used primarily
28			* in before/after constructions such as:
29			*
30			* <pre>
31			* class X {
32			* ReentrantLock lock;
33			* // ...
34			*
35			* public void m() {
36			* lock.lock(); // block until condition holds
37			* try {
38			* // ... method body
39			* } finally {
40			* lock.unlock()
41			* }
42			* }
43			* }
44			* </pre>
45			*
46			* <p>This class supports the interruption of lock acquisition and provides a
47			* {@link #newCondition Condition} implementation that supports the
48			* interruption of thread suspension.
49			*
50			* <p>Except where noted, passing a <tt>null</tt> value for any parameter
51			* will result in a {@link NullPointerException} being thrown.
52			*
53			* <h3>Implentation Notes</h3>
54			* <p> To-BE_DONE
55			*
56			*
57			* @since 1.5
58			* @spec JSR-166
59			* @revised $Date: 2003/02/06 06:41:13 $
60			* @editor $Author: dholmes $
61			*
62			* @fixme (1) We need a non-nested example to motivate this
63			* @fixme (2) Describe performance aspects of interruptible locking for the RI
64			**/
65			public class ReentrantLock implements Lock {
66
67			/**
68			* Creates an instance of <tt>ReentrantLock</tt>
69			*/
70			public ReentrantLock() {}
71
72			/**
73			* Acquirea the lock.
74			* <p>Acquires the lock if it is not held be another thread and returns
75			* immediately, setting the lock hold count to one.
76			* <p>If the current thread
77			* already holds the lock then the hold count is incremented by one and
78			* the method returns immediately.
79			* <p>If the lock is held by another thread then the
80			* the current thread thread becomes disabled for thread scheduling
81			* purposes and lies dormant until the lock has been acquired
82			* at which time the lock hold count is set to one.
83			*/
84			public void lock() {}
85
86			/**
87			* Acquires the lock unless the current thread is
88			* {@link Thread#interrupt interrupted}.
89			* <p>Acquires the lock if it is not held by another thread and returns
90			* immediately, setting the lock hold count to one.
91			* <p>If the current thread already holds this lock then the hold count
92			* is incremented by one and the method returns immediately.
93			* <p>If the lock is held by another thread then the
94			* the current thread becomes disabled for thread scheduling
95			* purposes and lies dormant until one of two things happens:
96			* <ul>
97			* <li> The lock is acquired by the current thread; or
98			* <li> Some other thread {@link Thread#interrupt interrupts} the current
99			* thread.
100			* </ul>
101			* <p>If the lock is acquired by the current thread then the lock hold
102			* count is set to one.
103			* <p>If the current thread:
104			* <ul>
105			* <li>has its interrupted status set on entry to this method; or
106			* <li>is {@link Thread#interrupt interrupted} while waiting to acquire
107			* the lock,
108			* </ul>
109			* then {@link InterruptedException} is thrown and the current thread's
110			* interrupted status is cleared. As this method is an explicit
111			* interruption point, preference is given to responding to the interrupt
112			* over reentrant acquisition of the lock.
113			*
114			* <h3>Implentation Notes</h3>
115			* <p> To-BE_DONE
116			*
117			* @throws InterruptedException if the current thread is interrupted
118			*/
119			public void lockInterruptibly() throws InterruptedException { }
120
121			/**
122			* Acquires the lock only if it is not held by another thread at the time
123			* of invocation.
124			* <p>Acquires the lock if it is not held by another thread and returns
125			* immediately with the value <tt>true</tt>, setting the lock hold count
126			* to one.
127			* <p> If the current thread
128			* already holds this lock then the hold count is incremented by one and
129			* the method returns <tt>true</code>.
130			* <p>If the lock is held by another thread then this method will return
131			* immediately with the value <tt>false</tt>.
132			*
133			* @return <tt>true</tt>if the lock was free and was acquired by the
134			* current thread, or the lock was already held by the current thread; and
135			* <tt>false</tt> otherwise.
136			*/
137			public boolean tryLock() {
138			return false;
139			}
140
141			/**
142			*
143			* Acquires the lock if it is not held by another thread within the given
144			* waiting time and the current thread has not been interrupted.
145			* <p>Acquires the lock if it is not held by another thread and returns
146			* immediately with the value <tt>true</tt>, setting the lock hold count
147			* to one.
148			* <p> If the current thread
149			* already holds this lock then the hold count is incremented by one and
150			* the method returns <tt>true</code>.
151			* <p>If the lock is held by another thread then the
152			* the current thread becomes disabled for thread scheduling
153			* purposes and lies dormant until one of three things happens:
154			* <ul>
155			* <li> The lock is acquired by the current thread; or
156			* <li> Some other thread {@link Thread#interrupt interrupts} the current
157			* thread; or
158			* <li> The specified waiting time elapses
159			* </ul>
160			* <p>If the lock is acquired then the value <tt>true</tt> is returned and
161			* the lock hold count is set to one.
162			* <p>If the current thread:
163			* <ul>
164			* <li>has its interrupted status set on entry to this method; or
165			* <li>is {@link Thread#interrupt interrupted} while waiting to acquire
166			* the lock,
167			* </ul>
168			* then {@link InterruptedException} is thrown and the current thread's
169			* interrupted status is cleared. As this method is an explicit
170			* interruption point, preference is given to responding to the interrupt
171			* over reentrant acquisition of the lock.
172			* <p>If the specified waiting time elapses then the value <tt>false</tt>
173			* is returned.
174			* <p>The given waiting time is a best-effort lower bound. If the time is
175			* less than or equal to zero, the method will not wait at all.
176			*
177			* <h3>Implentation Notes</h3>
178			* <p> To-BE_DONE
179			*
180			* @return <tt>true</tt> if the lock was free and was acquired by the
181			* current thread, or the lock was already held by the current thread; and
182			* <tt>false</tt> if the waiting time elapsed before the lock could be
183			* acquired.
184			*
185			* @throws InterruptedException if the current thread is interrupted
186			*/
187			public boolean tryLock(long timeout, TimeUnit granularity) throws InterruptedException {
188			return false;
189			}
190
191			/**
192			* Attempts to release this lock.
193			* <p>If the current thread is the holder of this lock then the hold count
194			* is decremented. If the hold count is now zero then the lock is released.
195			* <p>If the current thread is not the holder of this lock then
196			* {@link IllegalMonitorStateException} is thrown.
197			* @throws IllegalMonitorStateExeception if the current thread does not
198			* hold this lock.
199			*/
200			public void unlock() {}
201
202			/**
203			* Queries the number of holds on this lock by the current thread.
204			* <p>A thread has a hold on a lock for each lock action that is not
205			* matched by an unlock action.
206			* <p>The hold count information is typically only used for testing and
207			* debugging purposes. For example, if a certain section of code should
208			* not be entered with the lock already held then we can assert that
209			* fact:
210			* <pre>
211			* class X {
212			* ReentrantLock lock = new ReentrantLock();
213			* // ...
214			*
215			* public void m() {
216			* assert lock.getHoldCount() == 0;
217			* lock.lock();
218			* try {
219			* // ... method body
220			* } finally {
221			* lock.unlock()
222			* }
223			* }
224			* }
225			* </pre>
226			*
227			* @return the number of holds on this lock by current thread,
228			* or zero if this lock is not held by current thread.
229			**/
230			public int getHoldCount() {
231			return 0;
232			}
233
234			/**
235			* Queries if this lock is held by the current thread.
236			* <p>Analogous to the {@link Thread#holdsLock} method for built-in
237			* monitor locks, this method is typically used for debugging and
238			* testing. For example, a method that should only be called while
239			* a lock is held can assert that this is the case:
240			* <pre>
241			* class X {
242			* ReentrantLock lock = new ReentrantLock();
243			* // ...
244			*
245			* public void m() {
246			* assert lock.isHeldByCurrentThread();
247			* // ... method body
248			* }
249			* }
250			* </pre>
251			*
252			* @return <tt>true</tt> if current thread holds this lock and
253			* <tt>false</tt> otherwise.
254			**/
255			public boolean isHeldByCurrentThread() {
256			return false;
257			}
258
259			/**
260			* Returns a {@link Condition} instance for use with this
261			* {@link Lock} instance.
262			*
263			* <p>The returned {@link Condition} instance has the same behavior and
264			* usage
265			* restrictions with this lock as the {@link Object} monitor methods
266			* ({@link Object#wait() wait}, {@link Object#notify notify}, and
267			* {@link Object#notifyAll notifyAll}) have with the built-in monitor
268			* lock:
269			* <ul>
270			* <li>If this lock is not held when any of the {@link Condition}
271			* {@link Condition#await() waiting} or {@link Condition#signal signalling}
272			* methods are called, then an {@link IllegalMonitorStateException} is
273			* thrown.
274			* <li>When the condition {@link Condition#await() waiting} methods are
275			* called the lock is released and before they return the lock is
276			* reacquired and the lock hold count restored to what it was when the
277			* method was called.
278			* <li>If a thread is {@link Thread#interrupt interrupted} while waiting
279			* then the wait will terminate, an {@link InterruptedException} will be
280			* thrown, and the thread's interrupted status will be cleared.
281			* <li>The order in which waiting threads are signalled is not specified.
282			* <li>The order in which threads returning from a wait, and threads trying
283			* to acquire the lock, are granted the lock, is not specified.
284			* </ul>
285			*/
286			public Condition newCondition() {
287			return null;
288			}
289
290			}
291
292
293
294