cz.zcu.fav.kiv.jsim.ipc
Class JSimSemaphore

java.lang.Object
  cz.zcu.fav.kiv.jsim.ipc.JSimSemaphore

All Implemented Interfaces:

JSimDisplayable, java.lang.Comparable<JSimSemaphore>

public class JSimSemaphore
extends java.lang.Object
implements JSimDisplayable, java.lang.Comparable<JSimSemaphore>

A JSimSemaphore is a mean of synchronization of two or more J-Sim processes. Semaphores were invented by Edsger W. Dijkstra, Professor Emeritus of Computer Sciences and Mathematics at The University of Texas. Semaphores typically protect shared data from being accessed concurrently by two or more processes. Semaphore functions P() and V() serve as the beginning and the end of a critical section, preventing any process from passing over P() if another process has already passed over it. When the other process, being currently inside the critical section, invokes V() on the semaphore, it releases the semaphore and the process waiting on P() is woken up and enters the critical section. An integer counter and a queue are used for blocking and resuming processes. Caution: This implementation of semaphore can be used inside a J-Sim simulation only! It is not a mean of synchronization of Java threads! Important note: Semaphores can only be used by processes from the same simulation. An attempt to invoke a method of a semaphore of simulation S₁ from a process of simulation S₂ will cause an unpredictable and probably faulty behavior.

Since:

J-Sim version 0.3.0

Version:

J-Sim version 0.6.0

Author:

Jarda KAČER

Field Summary

private long	counter A counter of processes that can pass over P() without blocking.
private static java.util.logging.Logger	logger Common logger for all instances of this class.
private java.lang.String	myName The name of the semaphore.
private long	myNumber This semaphore's number.
protected JSimSimulation	myParent The simulation in which the semaphore is placed.
private java.util.LinkedList<JSimProcess>	queue A queue of processes blocked on this semaphore's P() function.

Constructor Summary

JSimSemaphore(java.lang.String name, JSimSimulation parent, long initCounter)
Creates a new semaphore with the specified name and initial value of the counter.

Method Summary

int	compareTo(JSimSemaphore s) Compares this semaphore with another one.
javax.swing.JDialog	createDetailedInfoWindow(JSimMainWindow parentWindow) Creates a detailed info window that shows information about the semaphore.
boolean	equals(java.lang.Object o) Indicates whether some other object is equal to this one.
long	getCounter() Returns this semaphore's counter.
java.util.Collection<JSimPair>	getDetailedInformationArray() Returns a collection with the semaphore's characteristics.
int	getNumberOfWaitingProcesses() Returns the number of processes blocked on this semaphore's P() function.
java.lang.String	getObjectListItemDescription() Returns a string containing basic information about the semaphore.
JSimSimulation	getParent() Returns the simulation that this semaphore is a part of.
java.lang.String	getSemaphoreName() Returns the semaphore's name.
long	getSemaphoreNumber() Returns the semaphore's number.
int	hashCode() Returns a hash code value for the object.
void	P() P() is a potentially blocking operation that denotes the beginning of a critical section.
java.lang.String	toString() Returns a string representation of the semaphore.
void	V() V() denotes the end of a critical section.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

logger

private static final java.util.logging.Logger logger

Common logger for all instances of this class. By default, all logging information goes to a file. Only severe events go to the console, in addition to a file.

myName

private final java.lang.String myName

The name of the semaphore.

myNumber

private final long myNumber

This semaphore's number. Semaphore numbers are unique for a given simulation.

myParent

protected final JSimSimulation myParent

The simulation in which the semaphore is placed. Protected because child classes will possibly want to use it.

counter

private long counter

A counter of processes that can pass over P() without blocking. This counter is decremented every time a process passes over P() without blocking and incremented every time V() is invoked and no process is blocked on P().

queue

private java.util.LinkedList<JSimProcess> queue

A queue of processes blocked on this semaphore's P() function.

Constructor Detail

JSimSemaphore

public JSimSemaphore(java.lang.String name,
                     JSimSimulation parent,
                     long initCounter)
              throws JSimInvalidParametersException,
                     JSimTooManySemaphoresException

Creates a new semaphore with the specified name and initial value of the counter. Every semaphore must belong to a simulation, as processes and queues. Important note: Semaphores can only be used by processes from the same simulation. An attempt to invoke a method of a semaphore of simulation S₁ from a process of simulation S₂ will cause an unpredictable and probably faulty behavior.

Parameters:

name - The name of the semaphore.

parent - The parent simulation that this semaphore belongs to.

initCounter - The initial value of the semaphore. It must be non-negative. The initial value determines the number of processes that can invoke P() without being blocked. A reasonable value is 1 in most cases. If you want to simulate a critical section, the value of 1 is the only choice.

Throws:

JSimInvalidParametersException - This exception is thrown out if the parent simulation is null or the initial value of the counter is invalid.

JSimTooManySemaphoresException - This exception is thrown out if no more semaphore can be added to the simulation.

Method Detail

P

public void P()
       throws JSimInvalidContextException

P() is a potentially blocking operation that denotes the beginning of a critical section. If the counter of processes using the semaphore is positive, the calling process passes beyond P(). Otherwise, it is blocked on the semaphore and remains blocked until a corresponding number of V() invocations is made. Important note: Semaphores can only be used by processes from the same simulation. An attempt to invoke a method of a semaphore of simulation S₁ from a process of simulation S₂ will cause an unpredictable and probably faulty behavior.

Throws:

JSimInvalidContextException - This exception is thrown out if this method is called from outside a process. This means that no process is currently running.

V

public void V()
       throws JSimInvalidContextException

V() denotes the end of a critical section. If the queue of waiting processes is empty, the counter is incremented. Otherwise, the first process waiting in the queue is woken up and can proceed with performing operations inside the critical section. The invocation of V() need not necessarily follow an invocation of P(). They can be invoked in the inverse order, even from different processes in some special cases. Important note: Semaphores can only be used by processes from the same simulation. An attempt to invoke a method of a semaphore of simulation S₁ from a process of simulation S₂ will cause an unpredictable and probably faulty behavior.

Throws:

JSimInvalidContextException - This exception is thrown out if this method is called from outside a process. This means that no process is currently running.

getNumberOfWaitingProcesses

public int getNumberOfWaitingProcesses()

Returns the number of processes blocked on this semaphore's P() function.

Returns:

The number of processes blocked on this semaphore's P() function.

getCounter

public long getCounter()

Returns this semaphore's counter.

Returns:

This semaphore's counter.

getSemaphoreNumber

public final long getSemaphoreNumber()

Returns the semaphore's number.

Returns:

The semaphore's number.

getSemaphoreName

public java.lang.String getSemaphoreName()

Returns the semaphore's name.

Returns:

The semaphore's name.

getParent

public JSimSimulation getParent()

Returns the simulation that this semaphore is a part of.

Returns:

The simulation that this semaphore is a part of.

getObjectListItemDescription

public java.lang.String getObjectListItemDescription()

Returns a string containing basic information about the semaphore. The string can be displayed in a JSimMainWindowList component.

Specified by:

getObjectListItemDescription in interface JSimDisplayable

Returns:

A string containing basic information about the semaphore.

getDetailedInformationArray

public java.util.Collection<JSimPair> getDetailedInformationArray()

Returns a collection with the semaphore's characteristics. Every characteristics contains a name and a value. The collection can be displayed in a JSimGUIDetailedInfoWindow table.

Specified by:

getDetailedInformationArray in interface JSimDisplayable

Returns:

A collection of the semaphore's characteristics.

createDetailedInfoWindow

public javax.swing.JDialog createDetailedInfoWindow(JSimMainWindow parentWindow)

Creates a detailed info window that shows information about the semaphore. Returns a reference to the created window.

Specified by:

createDetailedInfoWindow in interface JSimDisplayable

Returns:

A reference to the created info window.

toString

public java.lang.String toString()

Returns a string representation of the semaphore. Provided information: number, name, ...

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the semaphore.

compareTo

public int compareTo(JSimSemaphore s)

Compares this semaphore with another one. Returns a negative integer, zero, or a positive integer as this semaphore is less than, equal to, or greater than the specified object. It is assumed that the argument is also a JSimSemaphore. This class has a natural ordering that is fully consistent with equals(). If equals() returns true for s1 and s2, then compareTo() will return 0 for the same s1 and s2, and vice versa.

Specified by:

compareTo in interface java.lang.Comparable<JSimSemaphore>

Returns:

Zero if the numbers of both semaphores are equal, a negative number if the number of this semaphore is less than the other semaphore's number, and a positive number if the number of this semaphore is greater than the other semaphore's number.

Throws:

java.lang.ClassCastException - This exception is thrown out when the specified object cannot be typecasted to JSimSemaphore.

equals

public boolean equals(java.lang.Object o)

Indicates whether some other object is equal to this one. This implementation compares semaphore numbers and their simulations' numbers which is actually equal to simple reference comparison because semaphore numbers are unique for a given simulation and simulation numbers are unique for a given JVM instance. Unique semaphore numbers are assured by the constructor and the JSimSimulation.getFreeSemaphoreNumber() method. Unique simulation numbers are assured by the JSimSimulation constructor.

Overrides:

equals in class java.lang.Object

Parameters:

o - The reference object with which to compare.

Returns:

True if this object is the same as the obj argument, false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object. The hash code is computed from the semaphore's number and its simulation's number using the algorithm described in [UJJ3/166]. This implementation of hash code computation is fully consistent with equals().

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code for this semaphore.