util/concurrent/FifoSemaphore.java

package java.util.concurrent;

/**
 * A semaphore that guarantees that threads invoking
 * any of the {@link #acquire() acquire} methods 
 * are allocated permits in the order in 
 * which their invocation of those methods was processed (first-in-first-out).
 *
 * <p>This class introduces a fairness guarantee that can be useful
 * in some contexts.
 * However, it needs to be realized that the order in which invocations are
 * processed can be different from the order in which an application perceives
 * those invocations to be processed. Effectively, when no permit is available
 * each thread is stored in a FIFO queue. As permits are released, they
 * are allocated to the thread at the head of the queue, and so the order
 * in which threads enter the queue, is the order in which they come out.  
 * This order need not have any relationship to the order in which requests 
 * were made, nor the order in which requests actually return to the caller as 
 * these depend on the underlying thread scheduling, which is not guaranteed 
 * to be predictable or fair.
 *
 * <p>As permits are allocated in-order, this class also provides convenience
 * methods to {@link #acquire(long) acquire} and 
 * {@link #release(long) release} multiple permits at a time. 
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/05/14 21:30:46 $
 * @editor $Author: tim $
 *
 */
public class FifoSemaphore extends Semaphore {

    /**
     * Construct a <tt>FiFoSemaphore</tt> with the given number of
     * permits.
     * @param permits the initial number of permits available
     */
    public FifoSemaphore(long permits) { 
        super(permits); 
    }

    /**
     * Acquires a permit from this semaphore, blocking until one is
     * available, or the thread is {@link Thread#interrupt interrupted}.
     *
     * <p>This is equivalent to invoking {@link #acquire(long) acquire(1)}.
     *
     * @throws InterruptedException if the current thread is interrupted
     *
     * @see Thread#interrupt
     */
    public void acquire() throws InterruptedException {
        acquire(1);
    }

    /**
     * Acquires the given number of permits from this semaphore, 
     * blocking until all are available, 
     * or the thread is {@link Thread#interrupt interrupted}.
     *
     * <p>Acquires the given number of permits, if they are available,
     * and returns immediately,
     * reducing the number of available permits by the given amount.
     *
     * <p>If insufficient permits are available then the current thread becomes
     * disabled for thread scheduling purposes and lies dormant until
     * one of two things happens:
     * <ul>
     * <li>Some other thread invokes one of the {@link #release() release} 
     * methods for this semaphore, the current thread is next to be assigned
     * permits and the number of available permits satisfies this request; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread.
     * </ul>
     *
     * <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
     * for a permit,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared. 
     * Any available permits are assigned to the next waiting thread as if
     * they had been made available by a call to {@link #release()}.
     *
     * @param permits the number of permits to acquire
     *
     * @throws InterruptedException if the current thread is interrupted
     *
     * @see Thread#interrupt
     */
    public void acquire(long permits) throws InterruptedException {}

    /**
     * Acquires a permit from this semaphore, blocking until one is
     * available.
     *
     * <p>This is equivalent to invoking 
     * {@link #acquireUninterruptibly(long) acquireUninterruptibly(1)}.
     *
     */
    public void acquireUninterruptibly() {
        acquireUninterruptibly(1);
    }

    /**
     * Acquires the given number of permits from this semaphore, 
     * blocking until all are available.
     *
     * <p>Acquires the given number of permits, if they are available,
     * and returns immediately,
     * reducing the number of available permits by the given amount.
     *
     * <p>If insufficient permits are available then the current thread becomes
     * disabled for thread scheduling purposes and lies dormant until
     * some other thread invokes one of the {@link #release() release} 
     * methods for this semaphore, the current thread is next to be assigned
     * permits and the number of available permits satisfies this request.
     *
     * <p>If the current thread
     * is {@link Thread#interrupt interrupted} while waiting
     * for permits then it will continue to wait and its position in the
     * queue is not affected. When the
     * thread does return from this method its interrupt status will be set.
     *
     * @param permits the number of permits to acquire
     *
     */
    public void acquireUninterruptibly(long permits) {}

    /**
     * Acquires a permit from this semaphore, only if one is available at 
     * the time of invocation.
     *
     * <p>This is equivalent to invoking 
     * {@link #tryAcquire(long) tryAcquire(1)}.
     *
     * @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
     * otherwise.
     */
    public boolean tryAcquire() {
        return tryAcquire(1);
    }

    /**
     * Acquires the given number of permits from this semaphore, only if 
     * all are available at the  time of invocation.
     * <p>Acquires the given number of permits, if they are available, and 
     * returns immediately, with the value <tt>true</tt>,
     * reducing the number of available permits by the given amount.
     *
     * <p>If insufficient permits are available then this method will return
     * immediately with the value <tt>false</tt> and the number of available
     * permits is unchanged.
     *
     * @param permits the number of permits to acquire
     *
     * @return <tt>true</tt> if the permits were acquired and <tt>false</tt>
     * otherwise.
     */
    public boolean tryAcquire(long permits) {
        return false;
    }

    /**
     * Acquires a permit from this semaphore, if one becomes available 
     * within the given waiting time and the
     * current thread has not been {@link Thread#interrupt interrupted}.
     *
     * <p>This is equivalent to invoking 
     * {@link #tryAcquire(long, long, TimeUnit) 
     * tryAcquire(1, timeout, granularity)}.
     *
     * @param timeout the maximum time to wait for a permit
     * @param granularity the time unit of the <tt>timeout</tt> argument.
     * @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
     * if the waiting time elapsed before a permit was acquired.
     *
     * @throws InterruptedException if the current thread is interrupted
     *
     * @see Thread#interrupt
     *
     */
    public boolean tryAcquire(long timeout, TimeUnit granularity)
        throws InterruptedException {
        return tryAcquire(1, timeout, granularity);
    }

    /**
     * Acquires the given number of permits from this semaphore, if all 
     * become available within the given waiting time and the
     * current thread has not been {@link Thread#interrupt interrupted}.
     * <p>Acquires the given number of permits, if they are available and 
     * returns immediately, with the value <tt>true</tt>,
     * reducing the number of available permits by the given amount.
     * <p>If insufficient permits are available then
     * the current thread becomes disabled for thread scheduling
     * purposes and lies dormant until one of three things happens:
     * <ul>
     * <li>Some other thread invokes one of the {@link #release() release} 
     * methods for this semaphore, the current thread is next to be assigned
     * permits and the number of available permits satisfies this request; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread; or
     * <li>The specified waiting time elapses.
     * </ul>
     * <p>If the permits are acquired then the value <tt>true</tt> is returned.
     * <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 permits,
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's
     * interrupted status is cleared.
     * Any available permits are assigned to the next waiting thread as if
     * they had been made available by a call to {@link #release()}.
     *
     * <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.
     * Any available permits are assigned to the next waiting thread as if
     * they had been made available by a call to {@link #release()}.
     *
     * @param permits the number of permits to acquire
     * @param timeout the maximum time to wait for the permits
     * @param granularity the time unit of the <tt>timeout</tt> argument.
     * @return <tt>true</tt> if all permits were acquired and <tt>false</tt>
     * if the waiting time elapsed before all permits were acquired.
     *
     * @throws InterruptedException if the current thread is interrupted
     *
     * @see Thread#interrupt
     *
     */
    public boolean tryAcquire(long permits, long timeout, TimeUnit granularity)
        throws InterruptedException {
        return false;
    }


    /**
     * Releases a permit, returning it to the semaphore.
     * <p>This is equivalent to invoking {@link #release(long) release(1)}.
     */
    public void release() {
        release(1);
    }

    /**
     * Releases the given number of permits, returning them to the semaphore.
     * <p>Releases the given number of permits, increasing the number of 
     * available permits by that amount.
     * If any threads are blocking trying to acquire permits, then the
     * one that has been waiting the longest
     * is selected and given the permits that were just released.
     * If the number of available permits satisfies that thread's request
     * then that thread is re-enabled for thread scheduling purposes; otherwise
     * the thread continues to wait. If there are still permits available
     * after the first thread's request has been satisfied, then those permits
     * are assigned to the next waiting thread. If it is satisfied then it is
     * re-enabled for thread scheduling purposes. This continues until there
     * are insufficient permits to satisfy the next waiting thread, or there
     * are no more waiting threads.
     *
     * <p>There is no requirement that a thread that releases a permit must
     * have acquired that permit by calling {@link Semaphore#acquire acquire}.
     * Correct usage of a semaphore is established by programming convention
     * in the application.
     *
     * @param permits the number of permits to release
     */
    public void release(long permits) {}

}


Revision:	1.2
Committed:	Fri Jun 6 18:42:17 2003 UTC (21 years ago) by dl
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+2 -2 lines
State:	*FILE REMOVED*
Log Message:	Added to emulation Fixed some javadoc format errors
#	User	Rev	Content
1	tim	1.1	package java.util.concurrent;
2
3			/**
4			* A semaphore that guarantees that threads invoking
5			* any of the {@link #acquire() acquire} methods
6			* are allocated permits in the order in
7			* which their invocation of those methods was processed (first-in-first-out).
8			*
9			* <p>This class introduces a fairness guarantee that can be useful
10			* in some contexts.
11			* However, it needs to be realized that the order in which invocations are
12			* processed can be different from the order in which an application perceives
13			* those invocations to be processed. Effectively, when no permit is available
14			* each thread is stored in a FIFO queue. As permits are released, they
15			* are allocated to the thread at the head of the queue, and so the order
16			* in which threads enter the queue, is the order in which they come out.
17			* This order need not have any relationship to the order in which requests
18			* were made, nor the order in which requests actually return to the caller as
19			* these depend on the underlying thread scheduling, which is not guaranteed
20			* to be predictable or fair.
21			*
22			* <p>As permits are allocated in-order, this class also provides convenience
23			* methods to {@link #acquire(long) acquire} and
24			* {@link #release(long) release} multiple permits at a time.
25			*
26			* @since 1.5
27			* @spec JSR-166
28	dl	1.2	* @revised $Date: 2003/05/14 21:30:46 $
29			* @editor $Author: tim $
30	tim	1.1	*
31			*/
32			public class FifoSemaphore extends Semaphore {
33
34			/**
35			* Construct a <tt>FiFoSemaphore</tt> with the given number of
36			* permits.
37			* @param permits the initial number of permits available
38			*/
39			public FifoSemaphore(long permits) {
40			super(permits);
41			}
42
43			/**
44			* Acquires a permit from this semaphore, blocking until one is
45			* available, or the thread is {@link Thread#interrupt interrupted}.
46			*
47			* <p>This is equivalent to invoking {@link #acquire(long) acquire(1)}.
48			*
49			* @throws InterruptedException if the current thread is interrupted
50			*
51			* @see Thread#interrupt
52			*/
53			public void acquire() throws InterruptedException {
54			acquire(1);
55			}
56
57			/**
58			* Acquires the given number of permits from this semaphore,
59			* blocking until all are available,
60			* or the thread is {@link Thread#interrupt interrupted}.
61			*
62			* <p>Acquires the given number of permits, if they are available,
63			* and returns immediately,
64			* reducing the number of available permits by the given amount.
65			*
66			* <p>If insufficient permits are available then the current thread becomes
67			* disabled for thread scheduling purposes and lies dormant until
68			* one of two things happens:
69			* <ul>
70			* <li>Some other thread invokes one of the {@link #release() release}
71			* methods for this semaphore, the current thread is next to be assigned
72			* permits and the number of available permits satisfies this request; or
73			* <li>Some other thread {@link Thread#interrupt interrupts} the current
74			* thread.
75			* </ul>
76			*
77			* <p>If the current thread:
78			* <ul>
79			* <li>has its interrupted status set on entry to this method; or
80			* <li>is {@link Thread#interrupt interrupted} while waiting
81			* for a permit,
82			* </ul>
83			* then {@link InterruptedException} is thrown and the current thread's
84			* interrupted status is cleared.
85			* Any available permits are assigned to the next waiting thread as if
86			* they had been made available by a call to {@link #release()}.
87			*
88			* @param permits the number of permits to acquire
89			*
90			* @throws InterruptedException if the current thread is interrupted
91			*
92			* @see Thread#interrupt
93			*/
94			public void acquire(long permits) throws InterruptedException {}
95
96			/**
97			* Acquires a permit from this semaphore, blocking until one is
98			* available.
99			*
100			* <p>This is equivalent to invoking
101			* {@link #acquireUninterruptibly(long) acquireUninterruptibly(1)}.
102			*
103			*/
104			public void acquireUninterruptibly() {
105			acquireUninterruptibly(1);
106			}
107
108			/**
109			* Acquires the given number of permits from this semaphore,
110			* blocking until all are available.
111			*
112			* <p>Acquires the given number of permits, if they are available,
113			* and returns immediately,
114			* reducing the number of available permits by the given amount.
115			*
116			* <p>If insufficient permits are available then the current thread becomes
117			* disabled for thread scheduling purposes and lies dormant until
118			* some other thread invokes one of the {@link #release() release}
119			* methods for this semaphore, the current thread is next to be assigned
120			* permits and the number of available permits satisfies this request.
121			*
122			* <p>If the current thread
123			* is {@link Thread#interrupt interrupted} while waiting
124			* for permits then it will continue to wait and its position in the
125			* queue is not affected. When the
126			* thread does return from this method its interrupt status will be set.
127			*
128			* @param permits the number of permits to acquire
129			*
130			*/
131			public void acquireUninterruptibly(long permits) {}
132
133			/**
134			* Acquires a permit from this semaphore, only if one is available at
135			* the time of invocation.
136			*
137			* <p>This is equivalent to invoking
138			* {@link #tryAcquire(long) tryAcquire(1)}.
139			*
140			* @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
141			* otherwise.
142			*/
143			public boolean tryAcquire() {
144			return tryAcquire(1);
145			}
146
147			/**
148			* Acquires the given number of permits from this semaphore, only if
149			* all are available at the time of invocation.
150			* <p>Acquires the given number of permits, if they are available, and
151			* returns immediately, with the value <tt>true</tt>,
152			* reducing the number of available permits by the given amount.
153			*
154			* <p>If insufficient permits are available then this method will return
155			* immediately with the value <tt>false</tt> and the number of available
156			* permits is unchanged.
157			*
158			* @param permits the number of permits to acquire
159			*
160			* @return <tt>true</tt> if the permits were acquired and <tt>false</tt>
161			* otherwise.
162			*/
163			public boolean tryAcquire(long permits) {
164			return false;
165			}
166
167			/**
168			* Acquires a permit from this semaphore, if one becomes available
169			* within the given waiting time and the
170			* current thread has not been {@link Thread#interrupt interrupted}.
171			*
172			* <p>This is equivalent to invoking
173			* {@link #tryAcquire(long, long, TimeUnit)
174			* tryAcquire(1, timeout, granularity)}.
175			*
176			* @param timeout the maximum time to wait for a permit
177			* @param granularity the time unit of the <tt>timeout</tt> argument.
178			* @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
179			* if the waiting time elapsed before a permit was acquired.
180			*
181			* @throws InterruptedException if the current thread is interrupted
182			*
183			* @see Thread#interrupt
184			*
185			*/
186			public boolean tryAcquire(long timeout, TimeUnit granularity)
187			throws InterruptedException {
188			return tryAcquire(1, timeout, granularity);
189			}
190
191			/**
192			* Acquires the given number of permits from this semaphore, if all
193			* become available within the given waiting time and the
194			* current thread has not been {@link Thread#interrupt interrupted}.
195			* <p>Acquires the given number of permits, if they are available and
196			* returns immediately, with the value <tt>true</tt>,
197			* reducing the number of available permits by the given amount.
198			* <p>If insufficient permits are available then
199			* the current thread becomes disabled for thread scheduling
200			* purposes and lies dormant until one of three things happens:
201			* <ul>
202			* <li>Some other thread invokes one of the {@link #release() release}
203			* methods for this semaphore, the current thread is next to be assigned
204			* permits and the number of available permits satisfies this request; or
205			* <li>Some other thread {@link Thread#interrupt interrupts} the current
206			* thread; or
207			* <li>The specified waiting time elapses.
208			* </ul>
209			* <p>If the permits are acquired then the value <tt>true</tt> is returned.
210			* <p>If the current thread:
211			* <ul>
212			* <li>has its interrupted status set on entry to this method; or
213			* <li>is {@link Thread#interrupt interrupted} while waiting to acquire
214			* the permits,
215			* </ul>
216			* then {@link InterruptedException} is thrown and the current thread's
217			* interrupted status is cleared.
218			* Any available permits are assigned to the next waiting thread as if
219			* they had been made available by a call to {@link #release()}.
220			*
221			* <p>If the specified waiting time elapses then the value <tt>false</tt>
222			* is returned.
223			* The given waiting time is a best-effort lower bound. If the time is
224			* less than or equal to zero, the method will not wait at all.
225			* Any available permits are assigned to the next waiting thread as if
226			* they had been made available by a call to {@link #release()}.
227			*
228			* @param permits the number of permits to acquire
229			* @param timeout the maximum time to wait for the permits
230			* @param granularity the time unit of the <tt>timeout</tt> argument.
231			* @return <tt>true</tt> if all permits were acquired and <tt>false</tt>
232			* if the waiting time elapsed before all permits were acquired.
233			*
234			* @throws InterruptedException if the current thread is interrupted
235			*
236			* @see Thread#interrupt
237			*
238			*/
239			public boolean tryAcquire(long permits, long timeout, TimeUnit granularity)
240			throws InterruptedException {
241			return false;
242			}
243
244
245
246			/**
247			* Releases a permit, returning it to the semaphore.
248			* <p>This is equivalent to invoking {@link #release(long) release(1)}.
249			*/
250			public void release() {
251			release(1);
252			}
253
254			/**
255			* Releases the given number of permits, returning them to the semaphore.
256			* <p>Releases the given number of permits, increasing the number of
257			* available permits by that amount.
258			* If any threads are blocking trying to acquire permits, then the
259			* one that has been waiting the longest
260			* is selected and given the permits that were just released.
261			* If the number of available permits satisfies that thread's request
262			* then that thread is re-enabled for thread scheduling purposes; otherwise
263			* the thread continues to wait. If there are still permits available
264			* after the first thread's request has been satisfied, then those permits
265			* are assigned to the next waiting thread. If it is satisfied then it is
266			* re-enabled for thread scheduling purposes. This continues until there
267			* are insufficient permits to satisfy the next waiting thread, or there
268			* are no more waiting threads.
269			*
270			* <p>There is no requirement that a thread that releases a permit must
271			* have acquired that permit by calling {@link Semaphore#acquire acquire}.
272			* Correct usage of a semaphore is established by programming convention
273			* in the application.
274			*
275			* @param permits the number of permits to release
276			*/
277			public void release(long permits) {}
278
279			}
280
281
282
283
284