org.clapper.util.misc

Interface Semaphore

All Known Implementing Classes:

ObjectLockSemaphore

Deprecated.

J2SE 5.0 now provides a java.util.concurrent.Semaphore class

public interface Semaphore

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 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 acquire() method, and the V operation corresponds to the 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.

Method Summary

Modifier and Type	Method and Description
boolean	acquire() Deprecated. Acquire this semaphore.
boolean	acquire(long timeout) Deprecated. Acquire this semaphore.
void	addToCount(int delta) Deprecated. Increment the semaphore's current value, as well as its maximum value.
int	getValue() Deprecated. Get the semaphore's current value (i.e., its count).
void	release() Deprecated. Release this semaphore, incrementing its counter.

Method Detail

acquire

boolean acquire(long timeout)
         throws SemaphoreException

Deprecated.

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.

Parameters:

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."

Returns:

true if the semaphore was successfully acquired, false if the timeout expired.

Throws:

SemaphoreException - error attempting to acquire semaphore

See Also:

acquire()

acquire

boolean acquire()
         throws SemaphoreException

Deprecated.

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 acquire(long) with a timeout value of 0.

Returns:

true if the semaphore was successfully acquired, false if the timeout expired.

Throws:

SemaphoreException - error attempting to acquire semaphore

See Also:

acquire(long)

addToCount

void addToCount(int delta)
         throws SemaphoreException

Deprecated.

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.

Parameters:

delta - The amount by which to increment the count.

Throws:

SemaphoreException - error updating semaphore's count

getValue

int getValue()
      throws SemaphoreException

Deprecated.

Get the semaphore's current value (i.e., its count).

Returns:

the current value of the semaphore

Throws:

SemaphoreException - error getting semaphore's value

release

void release()
      throws SemaphoreException

Deprecated.

Release this semaphore, incrementing its counter.

Throws:

SemaphoreException - error getting semaphore's value