harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hinde...@apache.org
Subject svn commit: r798469 [12/28] - in /harmony/enhanced/classlib/branches/java6: ./ depends/build/platform/ depends/files/ depends/jars/ depends/manifests/icu4j_4.0/ depends/manifests/icu4j_4.2.1/ depends/manifests/icu4j_4.2.1/META-INF/ make/ modules/access...
Date Tue, 28 Jul 2009 09:30:48 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/Semaphore.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/Semaphore.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/Semaphore.java
(original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/Semaphore.java
Tue Jul 28 09:30:33 2009
@@ -14,7 +14,7 @@
  * 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
+ * However, no actual permit objects are used; the {@code Semaphore} just
  * keeps a count of the number available and acts accordingly.
  *
  * <p>Semaphores are often used to restrict the number of threads than can
@@ -22,7 +22,7 @@
  * a class that uses a semaphore to control access to a pool of items:
  * <pre>
  * class Pool {
- *   private static final MAX_AVAILABLE = 100;
+ *   private static final int MAX_AVAILABLE = 100;
  *   private final Semaphore available = new Semaphore(MAX_AVAILABLE, true);
  *
  *   public Object getItem() throws InterruptedException {
@@ -93,15 +93,19 @@
  * guarantees about the order in which threads acquire permits. In
  * particular, <em>barging</em> is permitted, that is, a thread
  * invoking {@link #acquire} can be allocated a permit ahead of a
- * thread that has been waiting.  When fairness is set true, the
+ * thread that has been waiting - logically the new thread places itself at
+ * the head of the queue of waiting threads. When fairness is set true, the
  * semaphore guarantees that threads invoking any of the {@link
- * #acquire() acquire} methods are allocated permits in the order in
+ * #acquire() acquire} methods are selected to obtain permits in the order in
  * which their invocation of those methods was processed
  * (first-in-first-out; FIFO). Note that FIFO ordering necessarily
  * applies to specific internal points of execution within these
  * methods.  So, it is possible for one thread to invoke
- * <tt>acquire</tt> before another, but reach the ordering point after
+ * {@code acquire} before another, but reach the ordering point after
  * the other, and similarly upon return from the method.
+ * Also note that the untimed {@link #tryAcquire() tryAcquire} methods do not
+ * honor the fairness setting, but will take any permits that are
+ * available.
  *
  * <p>Generally, semaphores used to control resource access should be
  * initialized as fair, to ensure that no thread is starved out from
@@ -114,6 +118,12 @@
  * permits at a time.  Beware of the increased risk of indefinite
  * postponement when these methods are used without fairness set true.
  *
+ * <p>Memory consistency effects: Actions in a thread prior to calling
+ * a "release" method such as {@code release()}
+ * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+ * actions following a successful "acquire" method such as {@code acquire()}
+ * in another thread.
+ *
  * @since 1.5
  * @author Doug Lea
  *
@@ -130,10 +140,12 @@
      * versions.
      */
     abstract static class Sync extends AbstractQueuedSynchronizer {
+        private static final long serialVersionUID = 1192457210091910933L;
+
         Sync(int permits) {
             setState(permits);
         }
-        
+
         final int getPermits() {
             return getState();
         }
@@ -147,11 +159,11 @@
                     return remaining;
             }
         }
-        
+
         protected final boolean tryReleaseShared(int releases) {
             for (;;) {
                 int p = getState();
-                if (compareAndSetState(p, p + releases)) 
+                if (compareAndSetState(p, p + releases))
                     return true;
             }
         }
@@ -178,10 +190,12 @@
      * NonFair version
      */
     final static class NonfairSync extends Sync {
+        private static final long serialVersionUID = -2694183684443567898L;
+
         NonfairSync(int permits) {
             super(permits);
         }
-       
+
         protected int tryAcquireShared(int acquires) {
             return nonfairTryAcquireShared(acquires);
         }
@@ -191,10 +205,12 @@
      * Fair version
      */
     final static class FairSync extends Sync {
+        private static final long serialVersionUID = 2014338818796000944L;
+
         FairSync(int permits) {
             super(permits);
         }
-        
+
         protected int tryAcquireShared(int acquires) {
             Thread current = Thread.currentThread();
             for (;;) {
@@ -211,57 +227,59 @@
     }
 
     /**
-     * Creates a <tt>Semaphore</tt> with the given number of
+     * Creates a {@code Semaphore} with the given number of
      * permits and nonfair fairness setting.
-     * @param permits the initial number of permits available. This
-     * value may be negative, in which case releases must
-     * occur before any acquires will be granted.
+     *
+     * @param permits the initial number of permits available.
+     *        This value may be negative, in which case releases
+     *        must occur before any acquires will be granted.
      */
-    public Semaphore(int permits) { 
+    public Semaphore(int permits) {
         sync = new NonfairSync(permits);
     }
 
     /**
-     * Creates a <tt>Semaphore</tt> with the given number of
+     * Creates a {@code Semaphore} with the given number of
      * permits and the given fairness setting.
-     * @param permits the initial number of permits available. This
-     * value may be negative, in which case releases must
-     * occur before any acquires will be granted.
-     * @param fair true if this semaphore will guarantee first-in
-     * first-out granting of permits under contention, else false.
+     *
+     * @param permits the initial number of permits available.
+     *        This value may be negative, in which case releases
+     *        must occur before any acquires will be granted.
+     * @param fair {@code true} if this semaphore will guarantee
+     *        first-in first-out granting of permits under contention,
+     *        else {@code false}
      */
-    public Semaphore(int permits, boolean fair) { 
+    public Semaphore(int permits, boolean fair) {
         sync = (fair)? new FairSync(permits) : new NonfairSync(permits);
     }
 
     /**
      * Acquires a permit from this semaphore, blocking until one is
-     * available, or the thread is {@link Thread#interrupt interrupted}.
+     * available, or the thread is {@linkplain 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 is next to be assigned a permit; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread.
+     * <li>Some other thread {@linkplain 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
+     * <li>is {@linkplain 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 {
         sync.acquireSharedInterruptibly(1);
@@ -273,103 +291,105 @@
      *
      * <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 is next to be assigned a 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.
-     *
+     * <p>If the current thread is {@linkplain 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() {
         sync.acquireShared(1);
     }
 
     /**
-     * Acquires a permit from this semaphore, only if one is available at the 
+     * 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>,
+     * with the value {@code true},
      * 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>.
+     * immediately with the value {@code false}.
      *
      * <p>Even when this semaphore has been set to use a
-     * fair ordering policy, a call to <tt>tryAcquire()</tt> <em>will</em>
+     * fair ordering policy, a call to {@code tryAcquire()} <em>will</em>
      * immediately acquire a permit if one is available, whether or not
-     * other threads are currently waiting. 
-     * This &quot;barging&quot; behavior can be useful in certain 
+     * other threads are currently waiting.
+     * This &quot;barging&quot; behavior can be useful in certain
      * circumstances, even though it breaks fairness. If you want to honor
-     * the fairness setting, then use 
+     * the fairness setting, then use
      * {@link #tryAcquire(long, TimeUnit) tryAcquire(0, TimeUnit.SECONDS) }
      * which is almost equivalent (it also detects interruption).
      *
-     * @return <tt>true</tt> if a permit was acquired and <tt>false</tt>
-     * otherwise.
+     * @return {@code true} if a permit was acquired and {@code false}
+     *         otherwise
      */
     public boolean tryAcquire() {
         return sync.nonfairTryAcquireShared(1) >= 0;
     }
 
     /**
-     * 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}.
+     * Acquires a permit from this semaphore, if one becomes available
+     * within the given waiting time and the current thread has not
+     * been {@linkplain Thread#interrupt interrupted}.
+     *
      * <p>Acquires a permit, if one is available and returns immediately,
-     * with the value <tt>true</tt>,
+     * with the value {@code true},
      * 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:
+     *
+     * <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 is next to be assigned a permit; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     * <li>Some other thread {@linkplain 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 a permit is acquired then the value {@code true} 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,
+     * <li>is {@linkplain 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.
-     * 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 unit 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.
+     * <p>If the specified waiting time elapses then the value {@code false}
+     * is returned.  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 unit the time unit of the {@code timeout} argument
+     * @return {@code true} if a permit was acquired and {@code false}
+     *         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 unit) 
+    public boolean tryAcquire(long timeout, TimeUnit unit)
         throws InterruptedException {
         return sync.tryAcquireSharedNanos(1, unit.toNanos(timeout));
     }
 
     /**
      * 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>Releases a permit, increasing the number of available permits by
+     * one.  If any threads are 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
@@ -378,45 +398,42 @@
     public void release() {
         sync.releaseShared(1);
     }
-       
+
     /**
-     * Acquires the given number of permits from this semaphore, 
-     * blocking until all are available, 
-     * or the thread is {@link Thread#interrupt interrupted}.
+     * Acquires the given number of permits from this semaphore,
+     * blocking until all are available,
+     * or the thread is {@linkplain 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.
+     * 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} 
+     * <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.
+     * <li>Some other thread {@linkplain 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
+     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
      * for a permit,
      * </ul>
      * then {@link InterruptedException} is thrown and the current thread's
-     * interrupted status is cleared. 
-     * Any permits that were to be assigned to this thread are instead 
-     * assigned to the next waiting thread(s), as if
-     * they had been made available by a call to {@link #release()}.
+     * interrupted status is cleared.
+     * Any permits that were to be assigned to this thread are instead
+     * assigned to other threads trying to acquire permits, as if
+     * permits 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
-     * @throws IllegalArgumentException if permits less than zero.
-     *
-     * @see Thread#interrupt
+     * @throws IllegalArgumentException if {@code permits} is negative
      */
     public void acquire(int permits) throws InterruptedException {
         if (permits < 0) throw new IllegalArgumentException();
@@ -424,27 +441,26 @@
     }
 
     /**
-     * Acquires the given number of permits from this semaphore, 
+     * 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.
+     * 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} 
+     * 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.
+     * <p>If the current thread is {@linkplain 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
-     * @throws IllegalArgumentException if permits less than zero.
+     * @throws IllegalArgumentException if {@code permits} is negative
      *
      */
     public void acquireUninterruptibly(int permits) {
@@ -456,16 +472,16 @@
      * 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>,
+     * <p>Acquires the given number of permits, if they are available, and
+     * returns immediately, with the value {@code true},
      * 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
+     * immediately with the value {@code false} and the number of available
      * permits is unchanged.
      *
      * <p>Even when this semaphore has been set to use a fair ordering
-     * policy, a call to <tt>tryAcquire</tt> <em>will</em>
+     * policy, a call to {@code tryAcquire} <em>will</em>
      * immediately acquire a permit if one is available, whether or
      * not other threads are currently waiting.  This
      * &quot;barging&quot; behavior can be useful in certain
@@ -475,10 +491,9 @@
      * which is almost equivalent (it also detects interruption).
      *
      * @param permits the number of permits to acquire
-     *
-     * @return <tt>true</tt> if the permits were acquired and <tt>false</tt>
-     * otherwise.
-     * @throws IllegalArgumentException if permits less than zero.
+     * @return {@code true} if the permits were acquired and
+     *         {@code false} otherwise
+     * @throws IllegalArgumentException if {@code permits} is negative
      */
     public boolean tryAcquire(int permits) {
         if (permits < 0) throw new IllegalArgumentException();
@@ -486,55 +501,54 @@
     }
 
     /**
-     * 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>,
+     * 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 {@linkplain Thread#interrupt interrupted}.
+     *
+     * <p>Acquires the given number of permits, if they are available and
+     * returns immediately, with the value {@code true},
      * 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} 
+     * <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>Some other thread {@linkplain 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 permits are acquired then the value {@code true} 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,
+     * <li>is {@linkplain 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 permits that were to be assigned to this thread, are instead 
-     * assigned to the next waiting thread(s), 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.
-     * If the time is
-     * less than or equal to zero, the method will not wait at all.
-     * Any permits that were to be assigned to this thread, are instead 
-     * assigned to the next waiting thread(s), as if
-     * they had been made available by a call to {@link #release()}.
+     * Any permits that were to be assigned to this thread, are instead
+     * assigned to other threads trying to acquire permits, as if
+     * the permits had been made available by a call to {@link #release()}.
+     *
+     * <p>If the specified waiting time elapses then the value {@code false}
+     * is returned.  If the time is less than or equal to zero, the method
+     * will not wait at all.  Any permits that were to be assigned to this
+     * thread, are instead assigned to other threads trying to acquire
+     * permits, as if the permits 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 unit 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.
-     *
+     * @param unit the time unit of the {@code timeout} argument
+     * @return {@code true} if all permits were acquired and {@code false}
+     *         if the waiting time elapsed before all permits were acquired
      * @throws InterruptedException if the current thread is interrupted
-     * @throws IllegalArgumentException if permits less than zero.
-     *
-     * @see Thread#interrupt
-     *
+     * @throws IllegalArgumentException if {@code permits} is negative
      */
     public boolean tryAcquire(int permits, long timeout, TimeUnit unit)
         throws InterruptedException {
@@ -544,19 +558,17 @@
 
     /**
      * Releases the given number of permits, returning them to the semaphore.
-     * <p>Releases the given number of permits, increasing the number of 
+     *
+     * <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
+     * If any threads are trying to acquire permits, then one
      * 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.
+     * then that thread is (re)enabled for thread scheduling purposes;
+     * otherwise the thread will wait until sufficient permits are available.
+     * If there are still permits available
+     * after this thread's request has been satisfied, then those permits
+     * are assigned in turn to other threads trying to acquire permits.
      *
      * <p>There is no requirement that a thread that releases a permit must
      * have acquired that permit by calling {@link Semaphore#acquire acquire}.
@@ -564,7 +576,7 @@
      * in the application.
      *
      * @param permits the number of permits to release
-     * @throws IllegalArgumentException if permits less than zero.
+     * @throws IllegalArgumentException if {@code permits} is negative
      */
     public void release(int permits) {
         if (permits < 0) throw new IllegalArgumentException();
@@ -573,16 +585,19 @@
 
     /**
      * Returns 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.
+     *
+     * @return the number of permits available in this semaphore
      */
     public int availablePermits() {
         return sync.getPermits();
     }
 
     /**
-     * Acquire and return all permits that are immediately available.
-     * @return the number of permits 
+     * Acquires and returns all permits that are immediately available.
+     *
+     * @return the number of permits acquired
      */
     public int drainPermits() {
         return sync.drainPermits();
@@ -592,19 +607,21 @@
      * Shrinks the number of available permits by the indicated
      * reduction. This method can be useful in subclasses that use
      * semaphores to track resources that become unavailable. This
-     * method differs from <tt>acquire</tt> in that it does not block
+     * method differs from {@code acquire} in that it does not block
      * waiting for permits to become available.
+     *
      * @param reduction the number of permits to remove
-     * @throws IllegalArgumentException if reduction is negative
+     * @throws IllegalArgumentException if {@code reduction} is negative
      */
     protected void reducePermits(int reduction) {
-	if (reduction < 0) throw new IllegalArgumentException();
+        if (reduction < 0) throw new IllegalArgumentException();
         sync.reducePermits(reduction);
     }
 
     /**
-     * Returns true if this semaphore has fairness set true.
-     * @return true if this semaphore has fairness set true.
+     * Returns {@code true} if this semaphore has fairness set true.
+     *
+     * @return {@code true} if this semaphore has fairness set true
      */
     public boolean isFair() {
         return sync instanceof FairSync;
@@ -612,25 +629,25 @@
 
     /**
      * Queries whether any threads are waiting to acquire. Note that
-     * because cancellations may occur at any time, a <tt>true</tt>
+     * because cancellations may occur at any time, a {@code true}
      * return does not guarantee that any other thread will ever
      * acquire.  This method is designed primarily for use in
      * monitoring of the system state.
      *
-     * @return true if there may be other threads waiting to acquire
-     * the lock.
+     * @return {@code true} if there may be other threads waiting to
+     *         acquire the lock
      */
-    public final boolean hasQueuedThreads() { 
+    public final boolean hasQueuedThreads() {
         return sync.hasQueuedThreads();
     }
 
     /**
-     * Returns an estimate of the number of threads waiting to
-     * acquire.  The value is only an estimate because the number of
-     * threads may change dynamically while this method traverses
-     * internal data structures.  This method is designed for use in
-     * monitoring of the system state, not for synchronization
-     * control.
+     * Returns an estimate of the number of threads waiting to acquire.
+     * The value is only an estimate because the number of threads may
+     * change dynamically while this method traverses internal data
+     * structures.  This method is designed for use in monitoring of the
+     * system state, not for synchronization control.
+     *
      * @return the estimated number of threads waiting for this lock
      */
     public final int getQueueLength() {
@@ -638,13 +655,13 @@
     }
 
     /**
-     * Returns a collection containing threads that may be waiting to
-     * acquire.  Because the actual set of threads may change
-     * dynamically while constructing this result, the returned
-     * collection is only a best-effort estimate.  The elements of the
-     * returned collection are in no particular order.  This method is
-     * designed to facilitate construction of subclasses that provide
-     * more extensive monitoring facilities.
+     * Returns a collection containing threads that may be waiting to acquire.
+     * Because the actual set of threads may change dynamically while
+     * constructing this result, the returned collection is only a best-effort
+     * estimate.  The elements of the returned collection are in no particular
+     * order.  This method is designed to facilitate construction of
+     * subclasses that provide more extensive monitoring facilities.
+     *
      * @return the collection of threads
      */
     protected Collection<Thread> getQueuedThreads() {
@@ -653,13 +670,12 @@
 
     /**
      * Returns a string identifying this semaphore, as well as its state.
-     * The state, in brackets, includes the String 
-     * &quot;Permits =&quot; followed by the number of permits.
-     * @return a string identifying this semaphore, as well as its
-     * state
+     * The state, in brackets, includes the String {@code "Permits ="}
+     * followed by the number of permits.
+     *
+     * @return a string identifying this semaphore, as well as its state
      */
     public String toString() {
         return super.toString() + "[Permits = " + sync.getPermits() + "]";
     }
-
 }



Mime
View raw message