semaphore.java

来自「SRI international 发布的OAA框架软件」· Java 代码 · 共 809 行 · 第 1/3 页

//     * </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 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
//     */
//    public void acquire(int permits) throws InterruptedException {
//        if (permits < 0) throw new IllegalArgumentException();
//        impl.acquire(permits);
//    }
//
//    /**
//     * 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
//     * @throws IllegalArgumentException if permits less than zero.
//     *
//     */
//    public void acquireUninterruptibly(int permits) {
//        if (permits < 0) throw new IllegalArgumentException();
//        boolean wasInterrupted = false;
//        while (true) {
//            try {
//                impl.acquire(permits);
//                if (wasInterrupted) {
//                    Thread.currentThread().interrupt();
//                }
//                return;
//            }
//            catch (InterruptedException e) {
//                wasInterrupted = true;
//            }
//        }
//    }
//
//    /**
//     * 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.
//     *
//     * <p>Even when this semaphore has been set to use a fair ordering
//     * policy, a call to <tt>tryAcquire</tt> <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
//     * circumstances, even though it breaks fairness. If you want to
//     * honor the fairness setting, then use {@link #tryAcquire(int,
//     * long, TimeUnit) tryAcquire(permits, 0, TimeUnit.SECONDS) }
//     * 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.
//     */
//    public boolean tryAcquire(int permits) {
//        if (permits < 0) throw new IllegalArgumentException();
//        return impl.attempt(permits);
//    }
//
//    /**
//     * 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 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 <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 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.
//     *
//     * @throws InterruptedException if the current thread is interrupted
//     * @throws IllegalArgumentException if permits less than zero.
//     *
//     * @see Thread#interrupt
//     *
//     */
//    public boolean tryAcquire(int permits, long timeout, TimeUnit unit)
//        throws InterruptedException {
//        if (permits < 0) throw new IllegalArgumentException();
//        return impl.attempt(permits, unit.toNanos(timeout));
//    }

    /**
     * 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 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 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}.
     * Correct usage of a semaphore is established by programming convention
     * in the application.
     *
     * @param permits the number of permits to release
     * @throws IllegalArgumentException if permits less than zero.
     */
    public void release(int permits) {
        if (permits < 0) throw new IllegalArgumentException();
        impl.release(permits);
    }

    /**
     * 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.
     */
    public int availablePermits() {
        return impl.getPermits();
    }

    /**
     * Acquire and return all permits that are immediately available.
     * @return the number of permits
     */
    public int drainPermits() {
        return impl.drain();
    }

    /**
     * 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
     * waiting for permits to become available.
     * @param reduction the number of permits to remove
     * @throws IllegalArgumentException if reduction is negative
     */
    protected void reducePermits(int reduction) {
        if (reduction < 0) throw new IllegalArgumentException();
        impl.reduce(reduction);
    }

    /**
     * Returns true if this semaphore has fairness set true.
     * @return true if this semaphore has fairness set true.
     */
    public boolean isFair() {
        return impl instanceof FairImpl;
    }

    /**
     * Queries whether any threads are waiting to acquire. Note that
     * because cancellations may occur at any time, a <tt>true</tt>
     * 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.
     */
    public final boolean hasQueuedThreads() {
        return impl.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.
     * @return the estimated number of threads waiting for this lock
     */
    public final int getQueueLength() {
        return impl.getQueueLength();
    }

    /**
     * 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 getQueuedThreads() {
        return impl.getQueuedThreads();
    }

    /**
     * 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
     */
    public String toString() {
        return super.toString() + "[Permits = " + impl.getPermits() + "]";
    }

}