util/concurrent/Semaphore.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;
import java.util.concurrent.locks.*;

/**
 * A counting semaphore.  Conceptually, a semaphore maintains a set of
 * permits.  Each {@link #acquire} blocks if necessary until a permit is
 * available, and then takes it.  Each {@link #release} adds a permit,
 * potentially releasing a blocking acquirer.
 * However, no actual permit objects are used; the <tt>Semaphore</tt> just
 * keeps a count of the number available and acts accordingly.
 *
 * <p>Semaphores are used to restrict the number of threads than can
 * access some (physical or logical) resource. For example, here is
 * a class that uses a semaphore to control access to a pool of items:
 * <pre>
 * class Pool {
 *   private static final MAX_AVAILABLE = 100;
 *   private final Semaphore available = new Semaphore(MAX_AVAILABLE);
 *
 *   public Object getItem() throws InterruptedException {
 *     available.acquire();
 *     return getNextAvailableItem();
 *   }
 *
 *   public void putItem(Object x) {
 *     if (markAsUnused(x))
 *       available.release();
 *   }
 *
 *   // Not a particularly efficient data structure; just for demo
 *
 *   protected Object[] items = ... whatever kinds of items being managed
 *   protected boolean[] used = new boolean[MAX_AVAILABLE];
 *
 *   protected synchronized Object getNextAvailableItem() {
 *     for (int i = 0; i < MAX_AVAILABLE; ++i) {
 *       if (!used[i]) {
 *          used[i] = true;
 *          return items[i];
 *       }
 *     }
 *     return null; // not reached
 *   }
 *
 *   protected synchronized boolean markAsUnused(Object item) {
 *     for (int i = 0; i < MAX_AVAILABLE; ++i) {
 *       if (item == items[i]) {
 *          if (used[i]) {
 *            used[i] = false;
 *            return true;
 *          } else
 *            return false;
 *       }
 *     }
 *     return false;
 *   }
 *
 * }
 * </pre>
 * <p>Before obtaining an item each thread must acquire a permit from the
 * semaphore, guaranteeing that an item is available for use. When the
 * thread has finished with the item it is returned back to the pool and
 * a permit is returned to the semaphore, allowing another thread to
 * acquire that item.
 * Note that no synchronization lock is held when {@link #acquire} is
 * called as that would prevent an item from being returned to the pool.
 * The semaphore encapsulates the synchronization needed to restrict access to
 * the pool, separately from any synchronization needed to maintain the
 * consistency of the pool itself.
 *
 * <p>A semaphore initialized to one, and which is used such that it only
 * has at most one permit available, can serve as a mutual exclusion lock.
 * This is more
 * commonly known as a <em>binary semaphore</em>, because it only has two
 * states: one permit available, or zero permits available.
 * When used in this way, the binary semaphore has the property (unlike many
 * {@link Lock} implementations, that the &quot;lock&quot; can be released by
 * a thread other than the owner (as semaphores have no notion of ownership).
 * This can be useful in some specialised contexts, such as deadlock recovery.
 *
 * <p>This class makes no guarantees about the order in which threads
 * acquire permits. In particular, barging is permitted, that is, a thread
 * invoking {@link #acquire} can be allocated a permit ahead of a thread
 * that has been waiting. If you need more deterministic guarantees, consider
 * using {@link FairSemaphore}.
 *
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/07/11 13:12:06 $
 * @editor $Author: dl $
 * @author Doug Lea
 *
 */
public class Semaphore implements java.io.Serializable {
    // todo SerialID
    // uses default serialization, which happens be fine here.

    // Fields are package-private to allow the FairSemaphore variant
    // to access.

    final ReentrantLock lock;
    final Condition available;
    long count;

    /** 
     * Package-private constructor used by FairSemaphore
     * @param permits the initial number of permits available
     * @param lock the lock to use
     */
    Semaphore(long permits, ReentrantLock lock) {
        this.count = permits;
        this.lock = lock;
        available = lock.newCondition();
    }

    /**
     * Construct a <tt>Semaphore</tt> with the given number of
     * permits.
     * @param permits the initial number of permits available
     */
    public Semaphore(long permits) {
        this(permits, new ReentrantLock());
    }

    /**
     * Acquires a permit from this semaphore, blocking until one is
     * available, or the thread is {@link Thread#interrupt interrupted}.
     *
     * <p>Acquires a permit, if one is available and returns immediately,
     * reducing the number of available permits by one.
     * <p>If no permit is 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 the {@link #release} method for this
     * semaphore and the current thread happens to be chosen as the
     * thread to receive the permit; 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.
     *
     * @throws InterruptedException if the current thread is interrupted
     *
     * @see Thread#interrupt
     */
    public void acquire() throws InterruptedException {
        lock.lockInterruptibly();
        try {
            while (count <= 0) 
                available.await();
            --count;
        } catch (InterruptedException ie) {
            available.signal();
            throw ie;
        } finally {
            lock.unlock();
        }
    }

    /**
     * Acquires a permit from this semaphore, blocking until one is
     * available.
     *
     * <p>Acquires a permit, if one is available and returns immediately,
     * reducing the number of available permits by one.
     * <p>If no permit is available then the current thread becomes
     * disabled for thread scheduling purposes and lies dormant until
     * some other thread invokes the {@link #release} method for this
     * semaphore and the current thread happens to be chosen as the
     * thread to receive the permit.
     *
     * <p>If the current thread
     * is {@link Thread#interrupt interrupted} while waiting
     * for a permit then it will continue to wait, but the time at which
     * the thread is assigned a permit may change compared to the time it
     * would have received the permit had no interruption occurred. When the
     * thread does return from this method its interrupt status will be set.
     *
     */
    public void acquireUninterruptibly() {
        lock.lock();
        try {
            while (count <= 0) 
                available.awaitUninterruptibly();
            --count;
        } finally {
            lock.unlock();
        }
    }

    /**
     * Acquires a permit from this semaphore, only if one is available at the 
     * time of invocation.
     * <p>Acquires a permit, if one is available and returns immediately,
     * with the value <tt>true</tt>,
     * reducing the number of available permits by one.
     *
     * <p>If no permit is available then this method will return
     * immediately with the value <tt>false</tt>.
     *
     * @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
     * otherwise.
     */
    public boolean tryAcquire() {
        lock.lock();
        try {
            if (count > 0) {
                --count;
                return true;
            }
            return false;
        } finally {
            lock.unlock();
        }
    }

    /**
     * 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>Acquires a permit, if one is available and returns immediately,
     * with the value <tt>true</tt>,
     * reducing the number of available permits by one.
     * <p>If no permit is 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 the {@link #release} method for this
     * semaphore and the current thread happens to be chosen as the
     * thread to receive the permit; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread; or
     * <li>The specified waiting time elapses.
     * </ul>
     * <p>If a permit is 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
     * a permit,
     * </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.
     *
     * @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 {
        lock.lockInterruptibly();
        long nanos = granularity.toNanos(timeout);
        try {
            for (;;) {
                if (count > 0) {
                    --count;
                    return true;
                }
                if (nanos <= 0)
                    return false;
                nanos = available.awaitNanos(nanos);
            }
        } catch (InterruptedException ie) {
            available.signal();
            throw ie;
        } finally {
            lock.unlock();
        }
    }

    /**
     * Releases a permit, returning it to the semaphore.
     * <p>Releases a permit, increasing the number of available permits
     * by one.
     * If any threads are blocking trying to acquire a permit, then one
     * is selected and given the permit that was just released.
     * That thread is re-enabled for thread scheduling purposes.
     * <p>There is no requirement that a thread that releases a permit must
     * have acquired that permit by calling {@link #acquire}.
     * Correct usage of a semaphore is established by programming convention
     * in the application.
     */
    public void release() {
        lock.lock();
        try {
            ++count;
            available.signal();
        } finally {
            lock.unlock();
        }
    }
        

    /**
     * Return the current number of permits available in this semaphore.
     * <p>This method is typically used for debugging and testing purposes.
     * @return the number of permits available in this semaphore.
     */
    public long availablePermits() {
        lock.lock();
        try {
            return count;
        } finally {
            lock.unlock();
        }
    }
}


Revision:	1.8
Committed:	Fri Aug 8 20:05:07 2003 UTC (20 years, 9 months ago) by tim
Branch:	MAIN
Changes since 1.7:	+10 -19 lines
Log Message:	Scrunched catch, finally, else clauses.
#	User	Rev	Content
1	dl	1.2	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5			*/
6
7	tim	1.1	package java.util.concurrent;
8	dl	1.5	import java.util.concurrent.locks.*;
9	tim	1.1
10			/**
11			* A counting semaphore. Conceptually, a semaphore maintains a set of
12			* permits. Each {@link #acquire} blocks if necessary until a permit is
13			* available, and then takes it. Each {@link #release} adds a permit,
14			* potentially releasing a blocking acquirer.
15			* However, no actual permit objects are used; the <tt>Semaphore</tt> just
16			* keeps a count of the number available and acts accordingly.
17			*
18			* <p>Semaphores are used to restrict the number of threads than can
19			* access some (physical or logical) resource. For example, here is
20			* a class that uses a semaphore to control access to a pool of items:
21			* <pre>
22			* class Pool {
23			* private static final MAX_AVAILABLE = 100;
24			* private final Semaphore available = new Semaphore(MAX_AVAILABLE);
25			*
26			* public Object getItem() throws InterruptedException {
27			* available.acquire();
28			* return getNextAvailableItem();
29			* }
30			*
31			* public void putItem(Object x) {
32			* if (markAsUnused(x))
33			* available.release();
34			* }
35			*
36			* // Not a particularly efficient data structure; just for demo
37			*
38			* protected Object[] items = ... whatever kinds of items being managed
39			* protected boolean[] used = new boolean[MAX_AVAILABLE];
40			*
41			* protected synchronized Object getNextAvailableItem() {
42			* for (int i = 0; i < MAX_AVAILABLE; ++i) {
43			* if (!used[i]) {
44			* used[i] = true;
45			* return items[i];
46			* }
47			* }
48			* return null; // not reached
49			* }
50			*
51			* protected synchronized boolean markAsUnused(Object item) {
52			* for (int i = 0; i < MAX_AVAILABLE; ++i) {
53			* if (item == items[i]) {
54			* if (used[i]) {
55			* used[i] = false;
56			* return true;
57	tim	1.8	* } else
58	tim	1.1	* return false;
59			* }
60			* }
61			* return false;
62			* }
63			*
64			* }
65			* </pre>
66			* <p>Before obtaining an item each thread must acquire a permit from the
67			* semaphore, guaranteeing that an item is available for use. When the
68			* thread has finished with the item it is returned back to the pool and
69			* a permit is returned to the semaphore, allowing another thread to
70			* acquire that item.
71			* Note that no synchronization lock is held when {@link #acquire} is
72			* called as that would prevent an item from being returned to the pool.
73			* The semaphore encapsulates the synchronization needed to restrict access to
74			* the pool, separately from any synchronization needed to maintain the
75			* consistency of the pool itself.
76			*
77			* <p>A semaphore initialized to one, and which is used such that it only
78			* has at most one permit available, can serve as a mutual exclusion lock.
79			* This is more
80			* commonly known as a <em>binary semaphore</em>, because it only has two
81			* states: one permit available, or zero permits available.
82			* When used in this way, the binary semaphore has the property (unlike many
83			* {@link Lock} implementations, that the "lock" can be released by
84			* a thread other than the owner (as semaphores have no notion of ownership).
85			* This can be useful in some specialised contexts, such as deadlock recovery.
86			*
87			* <p>This class makes no guarantees about the order in which threads
88			* acquire permits. In particular, barging is permitted, that is, a thread
89			* invoking {@link #acquire} can be allocated a permit ahead of a thread
90			* that has been waiting. If you need more deterministic guarantees, consider
91	dl	1.3	* using {@link FairSemaphore}.
92	tim	1.1	*
93			*
94			* @since 1.5
95			* @spec JSR-166
96	tim	1.8	* @revised $Date: 2003/07/11 13:12:06 $
97	dl	1.3	* @editor $Author: dl $
98	dl	1.4	* @author Doug Lea
99	tim	1.1	*
100			*/
101	dl	1.2	public class Semaphore implements java.io.Serializable {
102			// todo SerialID
103			// uses default serialization, which happens be fine here.
104
105			// Fields are package-private to allow the FairSemaphore variant
106			// to access.
107
108			final ReentrantLock lock;
109			final Condition available;
110			long count;
111	tim	1.1
112	dl	1.4	/**
113			* Package-private constructor used by FairSemaphore
114			* @param permits the initial number of permits available
115			* @param lock the lock to use
116			*/
117	dl	1.2	Semaphore(long permits, ReentrantLock lock) {
118			this.count = permits;
119			this.lock = lock;
120			available = lock.newCondition();
121			}
122	tim	1.1
123			/**
124			* Construct a <tt>Semaphore</tt> with the given number of
125			* permits.
126			* @param permits the initial number of permits available
127			*/
128			public Semaphore(long permits) {
129	dl	1.2	this(permits, new ReentrantLock());
130	tim	1.1	}
131
132			/**
133			* Acquires a permit from this semaphore, blocking until one is
134			* available, or the thread is {@link Thread#interrupt interrupted}.
135			*
136			* <p>Acquires a permit, if one is available and returns immediately,
137			* reducing the number of available permits by one.
138			* <p>If no permit is available then the current thread becomes
139			* disabled for thread scheduling purposes and lies dormant until
140			* one of two things happens:
141			* <ul>
142			* <li>Some other thread invokes the {@link #release} method for this
143			* semaphore and the current thread happens to be chosen as the
144			* thread to receive the permit; or
145			* <li>Some other thread {@link Thread#interrupt interrupts} the current
146			* thread.
147			* </ul>
148			*
149			* <p>If the current thread:
150			* <ul>
151			* <li>has its interrupted status set on entry to this method; or
152			* <li>is {@link Thread#interrupt interrupted} while waiting
153			* for a permit,
154			* </ul>
155			* then {@link InterruptedException} is thrown and the current thread's
156			* interrupted status is cleared.
157			*
158			* @throws InterruptedException if the current thread is interrupted
159			*
160			* @see Thread#interrupt
161			*/
162	dl	1.2	public void acquire() throws InterruptedException {
163			lock.lockInterruptibly();
164			try {
165	dl	1.4	while (count <= 0)
166			available.await();
167	dl	1.2	--count;
168	tim	1.8	} catch (InterruptedException ie) {
169	dl	1.2	available.signal();
170			throw ie;
171	tim	1.8	} finally {
172	dl	1.2	lock.unlock();
173			}
174			}
175	tim	1.1
176			/**
177			* Acquires a permit from this semaphore, blocking until one is
178			* available.
179			*
180			* <p>Acquires a permit, if one is available and returns immediately,
181			* reducing the number of available permits by one.
182			* <p>If no permit is available then the current thread becomes
183			* disabled for thread scheduling purposes and lies dormant until
184			* some other thread invokes the {@link #release} method for this
185			* semaphore and the current thread happens to be chosen as the
186			* thread to receive the permit.
187			*
188			* <p>If the current thread
189			* is {@link Thread#interrupt interrupted} while waiting
190			* for a permit then it will continue to wait, but the time at which
191			* the thread is assigned a permit may change compared to the time it
192			* would have received the permit had no interruption occurred. When the
193			* thread does return from this method its interrupt status will be set.
194			*
195			*/
196	dl	1.2	public void acquireUninterruptibly() {
197			lock.lock();
198			try {
199	dl	1.4	while (count <= 0)
200			available.awaitUninterruptibly();
201	dl	1.2	--count;
202	tim	1.8	} finally {
203	dl	1.2	lock.unlock();
204			}
205			}
206	tim	1.1
207			/**
208			* Acquires a permit from this semaphore, only if one is available at the
209			* time of invocation.
210			* <p>Acquires a permit, if one is available and returns immediately,
211			* with the value <tt>true</tt>,
212			* reducing the number of available permits by one.
213			*
214			* <p>If no permit is available then this method will return
215			* immediately with the value <tt>false</tt>.
216			*
217			* @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
218			* otherwise.
219			*/
220			public boolean tryAcquire() {
221	dl	1.2	lock.lock();
222			try {
223			if (count > 0) {
224			--count;
225			return true;
226			}
227			return false;
228	tim	1.8	} finally {
229	dl	1.2	lock.unlock();
230			}
231	tim	1.1	}
232
233			/**
234			* Acquires a permit from this semaphore, if one becomes available
235			* within the given waiting time and the
236			* current thread has not been {@link Thread#interrupt interrupted}.
237			* <p>Acquires a permit, if one is available and returns immediately,
238			* with the value <tt>true</tt>,
239			* reducing the number of available permits by one.
240			* <p>If no permit is available then
241			* the current thread becomes disabled for thread scheduling
242			* purposes and lies dormant until one of three things happens:
243			* <ul>
244			* <li>Some other thread invokes the {@link #release} method for this
245			* semaphore and the current thread happens to be chosen as the
246			* thread to receive the permit; or
247			* <li>Some other thread {@link Thread#interrupt interrupts} the current
248			* thread; or
249			* <li>The specified waiting time elapses.
250			* </ul>
251			* <p>If a permit is acquired then the value <tt>true</tt> is returned.
252			* <p>If the current thread:
253			* <ul>
254			* <li>has its interrupted status set on entry to this method; or
255			* <li>is {@link Thread#interrupt interrupted} while waiting to acquire
256			* a permit,
257			* </ul>
258			* then {@link InterruptedException} is thrown and the current thread's
259			* interrupted status is cleared.
260			* <p>If the specified waiting time elapses then the value <tt>false</tt>
261			* is returned.
262			* The given waiting time is a best-effort lower bound. If the time is
263			* less than or equal to zero, the method will not wait at all.
264			*
265			* @param timeout the maximum time to wait for a permit
266			* @param granularity the time unit of the <tt>timeout</tt> argument.
267			* @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
268			* if the waiting time elapsed before a permit was acquired.
269			*
270			* @throws InterruptedException if the current thread is interrupted
271			*
272			* @see Thread#interrupt
273			*
274			*/
275			public boolean tryAcquire(long timeout, TimeUnit granularity)
276			throws InterruptedException {
277	dl	1.2	lock.lockInterruptibly();
278			long nanos = granularity.toNanos(timeout);
279			try {
280			for (;;) {
281			if (count > 0) {
282			--count;
283			return true;
284			}
285			if (nanos <= 0)
286			return false;
287			nanos = available.awaitNanos(nanos);
288			}
289	tim	1.8	} catch (InterruptedException ie) {
290	dl	1.2	available.signal();
291			throw ie;
292	tim	1.8	} finally {
293	dl	1.2	lock.unlock();
294			}
295	tim	1.1	}
296
297			/**
298			* Releases a permit, returning it to the semaphore.
299			* <p>Releases a permit, increasing the number of available permits
300			* by one.
301			* If any threads are blocking trying to acquire a permit, then one
302			* is selected and given the permit that was just released.
303			* That thread is re-enabled for thread scheduling purposes.
304			* <p>There is no requirement that a thread that releases a permit must
305			* have acquired that permit by calling {@link #acquire}.
306			* Correct usage of a semaphore is established by programming convention
307			* in the application.
308			*/
309	dl	1.2	public void release() {
310	dl	1.7	lock.lock();
311	dl	1.2	try {
312			++count;
313			available.signal();
314	tim	1.8	} finally {
315	dl	1.2	lock.unlock();
316			}
317			}
318
319	tim	1.1
320			/**
321			* Return the current number of permits available in this semaphore.
322			* <p>This method is typically used for debugging and testing purposes.
323			* @return the number of permits available in this semaphore.
324			*/
325			public long availablePermits() {
326	dl	1.2	lock.lock();
327			try {
328			return count;
329	tim	1.8	} finally {
330	dl	1.2	lock.unlock();
331			}
332	tim	1.1	}
333			}
334
335
336