javax.realtime.DSS
Class DSS

java.lang.Object
  javax.realtime.DSS.DSS

public class DSS

extends java.lang.Object

The class implementing all discrete state simulation (DSS) features. Concepts and methods are directly modeled on Simula.

State variables are maintained as static variables, to eliminate the need to pass a reference to a DSS object to class instances using DSS features.

Supporting classes are EventList, EventNotice, and WaiterSet.

Author:

gary TO DO: optimize case for zero hold time?

Field Summary

static SimulationClock	clock The clock of this simulation.
static java.util.HashMap	eventBindings The HashMap mapping happening names to AsynchEvent's.
static EventList	eventList The EventList for this simulation.
static AbsoluteTime	nominalByteCodeCost
static java.lang.ThreadGroup	realtimeThreads
static TestClientStubs	testClient A fixed instance of TestClient used when running under JPF to hold main program state variables, e.g., accumulator variables maintained by JVM listeners.
static boolean	usingJPF true iff this program is being run under JPF, rather than a native JVM

Method Summary

static double	absoluteTimeNanos(AbsoluteTime time)
static void	activate(RealtimeThread thread) Activate the given thread at the current time.
static void	activate(RealtimeThread thread, AbsoluteTime time) Activate the given thread at the given time.
static void	activate(RealtimeThread thread, AbsoluteTime time, boolean verbose) Activate the given thread at given time.
static void	activate(RealtimeThread thread, boolean verbose) Activate the given thread at the current time.
static void	cancel(RealtimeThread thread) Remove any event notice for given thread.
static void	causeHappening(java.lang.String string) Cause a happening to occur, i.e., an external stimulus, which must be bound to an AsynchEvent.
static AbsoluteTime	currentTime() Fetches the current simulation time
static RelativeTime	fetchAndClearActivePhaseCost() If running under JPF, use the MJI interface to obtain the byte code execution cost of this active phase as observed through a JPF JVM listener.
static void	hold(RelativeTime t) Passivate and activate the current RealtimeThread at current time plus t.
static void	hold(RelativeTime t, boolean simulateActivePhaseTime)
static void	hold(RelativeTime t, boolean simulateActivePhaseTime, Resource resource) Passivate and activate the current RealtimeThread at current time plus t.
static void	hold(RelativeTime t, Resource resource)
static void	holdGivingUpResource(RelativeTime t, Resource resource, boolean simulateActivePhaseTime) Perform a hold operation bracketing it by release() and seize() operations on a resource.
static void	holdWithResource(RelativeTime holdTime, Resource resource, boolean simulateActivePhaseTime) Perform a hold operation wherein periods when the resource has been stolen do not count toward the hold time.
static void	passivate() Suspend current RealtimeThread without scheduling a reactivation scheduled event.
static void	passivate(boolean simulateActivePhaseCost) Suspend current RealtimeThread without scheduling a reactivation scheduled event.
static void	printTime() Print current time in format (millis ms, nanos ns)].
static void	reactivate(RealtimeThread thread) Cancel current thread, and activate at the current time.
static void	reactivate(RealtimeThread thread, AbsoluteTime time) Cancel current thread, and activate at given time.
static double	relativeTimeNanos(RelativeTime time)
static void	runSimulation() Run current simulation with no randomization.
static void	runSimulation(java.lang.String choiceMode) Run current simulation.
static void	shutdown() Abruptly shuts down the simulation.
static void	simulateActivePhaseCost() If running under JPF, simulate the time consumed thus far by this active phase.
static void	verifyChoiceMode(java.lang.String choiceMode)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

clock

public static SimulationClock clock

The clock of this simulation. This advances non-uniformly, as each EventNotice is dequeued from the EventList

eventList

public static EventList eventList

The EventList for this simulation.

eventBindings

public static java.util.HashMap eventBindings

The HashMap mapping happening names to AsynchEvent's.

usingJPF

public static boolean usingJPF

true iff this program is being run under JPF, rather than a native JVM

testClient

public static final TestClientStubs testClient

A fixed instance of TestClient used when running under JPF to hold main program state variables, e.g., accumulator variables maintained by JVM listeners.

realtimeThreads

public static java.lang.ThreadGroup realtimeThreads

nominalByteCodeCost

public static AbsoluteTime nominalByteCodeCost

Method Detail

holdGivingUpResource

public static void holdGivingUpResource(RelativeTime t,
                                        Resource resource,
                                        boolean simulateActivePhaseTime)
                                 throws java.lang.InterruptedException,
                                        ThreadTerminatedException

Perform a hold operation bracketing it by release() and seize() operations on a resource. This models a non-computational hold, e.g., waiting for a timer.

Parameters:

t - The hold time

resource - The resource

simulateActivePhaseTime - indicates whether the hold time should be increased by the observed byte code execution time of this active phase (must be running under JPF for this effect).

Throws:

java.lang.InterruptedException

ThreadTerminatedException

holdWithResource

public static void holdWithResource(RelativeTime holdTime,
                                    Resource resource,
                                    boolean simulateActivePhaseTime)
                             throws java.lang.InterruptedException,
                                    ThreadTerminatedException

Perform a hold operation wherein periods when the resource has been stolen do not count toward the hold time. This models computationally active periods, where progress cannot be made without possessing the resource.

Parameters:

holdTime - The hold time

resource - The resource

simulateActivePhaseTime - indicates whether the hold time should be increased by the observed byte code execution time of this active phase (must be running under JPF for this effect).

Throws:

java.lang.InterruptedException

ThreadTerminatedException

hold

public static void hold(RelativeTime t)
                 throws java.lang.InterruptedException

Passivate and activate the current RealtimeThread at current time plus t. The hold time should be increased by the observed byte code execution time of this active phase (must be running under JPF for this effect).

Parameters:

t - the duration of the hold

Throws:

java.lang.InterruptedException

hold

public static void hold(RelativeTime t,
                        Resource resource)
                 throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

hold

public static void hold(RelativeTime t,
                        boolean simulateActivePhaseTime)
                 throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

hold

public static void hold(RelativeTime t,
                        boolean simulateActivePhaseTime,
                        Resource resource)
                 throws java.lang.InterruptedException

Passivate and activate the current RealtimeThread at current time plus t.

Parameters:

t - the duration of the hold

simulateActivePhaseTime - indicates whether the hold time should be increased by the observed byte code execution time of this active phase (must be running under JPF for this effect).

Throws:

java.lang.InterruptedException

cancel

public static void cancel(RealtimeThread thread)

Remove any event notice for given thread. Should only be done remotely by some other thread.

Parameters:

thread - the RealtimeThread whose event notice is to be canceled.

passivate

public static void passivate()
                      throws java.lang.InterruptedException

Suspend current RealtimeThread without scheduling a reactivation scheduled event. The observed byte code execution time of this active phase should be simulated before passivating (must be running under JPF for this effect).

Throws:

java.lang.InterruptedException

passivate

public static void passivate(boolean simulateActivePhaseCost)
                      throws java.lang.InterruptedException

Suspend current RealtimeThread without scheduling a reactivation scheduled event.

Parameters:

simulateActivePhaseCost - indicates whether the observed byte code execution time of this active phase should be simulated before passivating (must be running under JPF for this effect).

Throws:

java.lang.InterruptedException

activate

public static void activate(RealtimeThread thread,
                            boolean verbose)

Activate the given thread at the current time. If thread already has an event notice, do nothing.

Parameters:

thread - the RealtimeThread to be activated.

verbose - indicates whether trace messages should be printed

activate

public static void activate(RealtimeThread thread)

Activate the given thread at the current time. If thread already has an event notice, do nothing. Do not print trace messages.

Parameters:

thread - the RealtimeThread to be activated.

activate

public static void activate(RealtimeThread thread,
                            AbsoluteTime time)

Activate the given thread at the given time. If thread already has an event notice, do nothing. Do not print trace messages.

Parameters:

thread - the RealtimeThread to be activated.

time - the activation time

activate

public static void activate(RealtimeThread thread,
                            AbsoluteTime time,
                            boolean verbose)

Activate the given thread at given time. If thread already has an event notice, do nothing. Note this permits a thread to activate itself, if running.

Parameters:

thread - the RealtimeThread to be activated.

time - the activation time

verbose - true if trace messages are desired

reactivate

public static void reactivate(RealtimeThread thread)

Cancel current thread, and activate at the current time.

Parameters:

thread - the RealtimeThread to be reactivated.

reactivate

public static void reactivate(RealtimeThread thread,
                              AbsoluteTime time)

Cancel current thread, and activate at given time.

Parameters:

thread - the RealtimeThread to be reactivated.

time - the reactivation time

printTime

public static void printTime()

Print current time in format (millis ms, nanos ns)].

runSimulation

public static void runSimulation()

Run current simulation with no randomization.

runSimulation

public static void runSimulation(java.lang.String choiceMode)

Run current simulation.

Parameters:

choiceMode - If equal to:

• nondeterministic Try all orderings of events scheduled at the same time and for draws from finite random distributions (valid only if running under JPF)
• pseudorandom pseudo-randomly select an order among events scheduled at the same time, and for draws from finite random distributions
• deterministic use FIFO selection among equal time events; no random draws are permitted

verifyChoiceMode

public static void verifyChoiceMode(java.lang.String choiceMode)

currentTime

public static AbsoluteTime currentTime()

Fetches the current simulation time

Returns:

current simulation time.

causeHappening

public static void causeHappening(java.lang.String string)
                           throws UnknownHappeningException

Cause a happening to occur, i.e., an external stimulus, which must be bound to an AsynchEvent.

Parameters:

string - name of external happening

Throws:

UnknownHappeningException - if happening name is unknown to system

UnknownHappeningException

fetchAndClearActivePhaseCost

public static RelativeTime fetchAndClearActivePhaseCost()

If running under JPF, use the MJI interface to obtain the byte code execution cost of this active phase as observed through a JPF JVM listener. Clear the cost accumulator variable, i.e., start a new logging period.

Otherwise, return null

Returns:

the observed (idealized) execution time of this active phase

simulateActivePhaseCost

public static void simulateActivePhaseCost()
                                    throws java.lang.InterruptedException

If running under JPF, simulate the time consumed thus far by this active phase.

Throws:

java.lang.InterruptedException

shutdown

public static void shutdown()
                     throws ThreadTerminatedException

Abruptly shuts down the simulation.

Throws:

ThreadTerminatedException

absoluteTimeNanos

public static double absoluteTimeNanos(AbsoluteTime time)

relativeTimeNanos

public static double relativeTimeNanos(RelativeTime time)