/*---------------------------------------------------------------------------*\
$Id: a129e9f2dfc0013e49c06662fd30ffe8d8475c91 $
---------------------------------------------------------------------------
This software is released under a BSD-style license:
Copyright (c) 2004-2007 Brian M. Clapper. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. The end-user documentation included with the redistribution, if any,
must include the following acknowlegement:
"This product includes software developed by Brian M. Clapper
(bmc@clapper.org, http://www.clapper.org/bmc/). That software is
copyright (c) 2004-2007 Brian M. Clapper."
Alternately, this acknowlegement may appear in the software itself,
if wherever such third-party acknowlegements normally appear.
3. Neither the names "clapper.org", "clapper.org Java Utility Library",
nor any of the names of the project contributors may be used to
endorse or promote products derived from this software without prior
written permission. For written permission, please contact
bmc@clapper.org.
4. Products derived from this software may not be called "clapper.org
Java Utility Library", nor may "clapper.org" appear in their names
without prior written permission of Brian M. Clapper.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL BRIAN M. CLAPPER BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\*---------------------------------------------------------------------------*/
package org.clapper.util.misc;
/**
* NOTE: This interface, and its subclasses, are deprecated. With
* J2SE 5.0 (a.k.a., Java 1.5), the JDK provides its own semaphore class,
* java.util.concurrent.Semaphore.
*
* The Semaphore interface specifies a classic counting
* semaphore. This interface can be implemented in a variety of ways, including
* (but not limited to) the following:
*
*
* - using the Java object-locking primitives (see, for instance,
* the {@link ObjectLockSemaphore})
*
- using the Java Native Interface (JNI) to access an underlying
* operating system semaphore primitive (e.g., the System V semaphore
* service on a Unix system)
*
*
* The following description of a semaphore is paraphrased from An
* Introduction to Operating Systems, by Harvey M. Deitel
* (Addison-Wesley, 1983, p. 88):
*
*
*
* "[Edsgar] Dijkstra developed the concept of semaphores ... as an aid
* to synchronizing processes. A semaphore is a variable that can be
* operated upon only by the synchronizing primitives, P and V (letters
* corresponding to words in Dijkstra's native language, Dutch) defined as
* follows:
*
*
* - P(S): wait for S to become greater than zero and then
* subtract 1 from S and proceed
*
- V(S): add 1 to S and then proceed
*
*
* "P allows a process to block itself voluntarily while it waits for
* an event to occur. V allows another process to wake up a blocked
* process. Each of these operations must be performed indivisibly; that
* is, the are not interruptible. The V-operation cannot block the process
* that performs it."
*
*
*
* Within this Semaphore class, the P operation corresponds to
* the {@link #acquire()} method, and the V operation corresponds to the
* {@link #release()} method.
*
* In other programming languages, one common use for a semaphore is to
* lock a critical section. For example, a semaphore is often used to
* synchronize access to a data structure that's shared between one or more
* processes or threads. Since the Java language has built in support for
* interthread synchronization (via the synchronized keyword),
* semaphores are not needed for that purpose in Java.
*
* However, semaphores are still useful in some scenarios.
* Consider the case where you have a fixed-size pool of shared buffers to
* be shared between all running threads. For whatever reason, you cannot
* allocate more buffers; you're stuck with the fixed number. How do you
* control access to the buffers when there are more threads than there are
* buffers? A semaphore makes this job much easier:
*
*
* - Create a semaphore that's associated with the buffer pool.
*
- Initialize the semaphore's counter to the number of buffers in the
* pool.
*
- Whenever a thread wants a buffer, it must first acquire the semaphore.
*
- Whenever a thread releases a buffer back to the pool, it must also
* release the semaphore.
*
*
* If a thread attempts to allocate a buffer from the pool, and there is
* at least one buffer in the pool, the thread's attempt to acquire the
* semaphore will succeed, and it can safely get the buffer. However, if there
* are no buffers in the pool, the buffer pool semaphore will be 0, and the
* thread will have to wait until (a) a buffer is returned to the pool,
* which will "kick" the semaphore and awaken the thread, or (b) the
* semaphore's acquire() method times out.
*
* @version $Revision$
*
* @deprecated J2SE 5.0 now provides a java.util.concurrent.Semaphore class
*
* @author Copyright © 2004-2007 Brian M. Clapper
*/
public interface Semaphore
{
/*----------------------------------------------------------------------*\
Public Methods
\*----------------------------------------------------------------------*/
/**
* Acquire this semaphore. If the semaphore isn't available, the
* current thread is put to sleep until either (a) the semaphore is
* available, or (b) the timeout period expires.
*
* @param timeout Timeout period, in milliseconds. A value of 0 means
* "wait forever, until the semaphore is available." A
* negative value means "return immediately if the
* semaphore is not available."
*
* @return true if the semaphore was successfully acquired,
* false if the timeout expired.
*
* @throws SemaphoreException error attempting to acquire semaphore
*
* @see #acquire()
*/
public boolean acquire (long timeout)
throws SemaphoreException;
/**
* Acquire this semaphore. If the semaphore isn't available, this
* method waits forever for the semaphore to become available. Calling
* this version of acquire() is exactly equivalent to calling
* {@link #acquire(long)} with a timeout value of 0.
*
* @throws SemaphoreException error attempting to acquire semaphore
*
* @see #acquire(long)
*/
public boolean acquire()
throws SemaphoreException;
/**
* Increment the semaphore's current value, as well as its maximum value.
* This method is useful in cases where the semaphore is controlling
* access to multiple instances of a resource (e.g, database connections,
* file descriptors, etc.), and more instances of the controlled resource
* have become available.
*
* @param delta The amount by which to increment the count.
*
* @throws SemaphoreException error updating semaphore's count
*/
public void addToCount (int delta)
throws SemaphoreException;
/**
* Get the semaphore's current value (i.e., its count).
*
* @return the current value of the semaphore
*
* @throws SemaphoreException error getting semaphore's value
*/
public int getValue()
throws SemaphoreException;
/**
* Release this semaphore, incrementing its counter.
*
* @throws SemaphoreException error getting semaphore's value
*/
public void release()
throws SemaphoreException;
}
Ads help maintain this website.