de.cau.cs.kieler.sj
Class EmbeddedSJProgram<StateLabel extends Enum<?>>

java.lang.Object
  extended by de.cau.cs.kieler.sj.EmbeddedSJProgram<StateLabel>
Type Parameters:
StateLabel - This parameter is used to tell the program all labels existing in the concrete SJ program. By using this parameter we are able to make sure that every label we working with is existing in the enumeration of labels in the sub class.
Direct Known Subclasses:
EmbeddedABRO, SJProgram

public abstract class EmbeddedSJProgram<StateLabel extends Enum<?>>
extends Object

Basic class for synchronous programming in java. Use this class via extends to write a synchronous java program. This class contains the methods to control the program.

See Also:
EmbeddedABRO
Rating red

Field Summary
static int INITIAL_TICK
          Value of the tickNr if the program is in the initial tick.
 
Constructor Summary
EmbeddedSJProgram(StateLabel startLabel, int prio)
          The constructor to start a new SJ-program.
EmbeddedSJProgram(StateLabel startLabel, int prio, SJLogger myLogger)
          The constructor to start a new SJ-program.
 
Method Summary
 void abort()
          Does a abort to all descendant created by the thread currently running.
 void activateCausalityCheck()
          Activates the causality check for all signals of the program.
 void addSignals(Signal... declaredSignals)
          Method to declare signal used by SJ.
 boolean awaitDoneCB(Signal signal)
          Waits for a signal after a initial pause.
 Signal[] doTick(Signal... inputs)
          Do a tick in the SJ program.
 void fork(StateLabel label, int prio)
          Part of a Process to execute 2 Program parts in a simulated parallel way.
 void forkEB(StateLabel label)
          Ends a number of forks and says there this thread should continue after the forks.
 SJLogger getLogger()
          Returns the logger used by this program.
 String getName()
          Returns the name of the program.
 Signal[] getSignals()
          Returns all signals known by the program.
 int getTickNr()
          Returns the Number of the current tick.
 void gotoB(StateLabel label)
          Goes to a label and continue with the code at this label.
 void haltCB()
          Halts at the current position.
 boolean isCausalityCheckActive()
          Tells if the causality check is active.
 boolean isInInitialTick()
          Gives you a information if the program is in the initial tick and not has been started.
 boolean isTerminated()
          Tells us if a SJ program is terminated.
 boolean isThreadRunning()
          Tells us if at the moment a thread is running.
 boolean isTickDone()
          Return true if the current tick is Done.
 boolean joinDoneCB()
          Joins threads by checking if all created descendants of the current thread are executed successful.
 void pauseB(StateLabel resumeLabel)
          Stops the execution of the state in which it is used for the current tick.
 void prioB(StateLabel label, int prio)
          Changes the priority of a thread and cause a new schedule.
 void removeSignals(Signal... declaredSignals)
          Removes signals and so undeclare them.
 void setLogger(SJLogger myLogger)
          Set the logger to log the JSON informations about the program.
 StateLabel state()
          Returns the next state (also called thread) to execute of a program.
 void suspend()
          Suspends all descendants threads of the current thread.
 void termB()
          Terminates the current Thread.
abstract  void tick()
          Function that should be implemented with a SJ-Program.
 String toString()
           
 void transB(StateLabel label)
          Aborts all descendants and their descendants of the executing thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

INITIAL_TICK

public static final int INITIAL_TICK
Value of the tickNr if the program is in the initial tick.

See Also:
Constant Field Values
Constructor Detail

EmbeddedSJProgram

public EmbeddedSJProgram(StateLabel startLabel,
                         int prio)
The constructor to start a new SJ-program. Using this constructor should always be the first then you start a SJ-program. The normal place to use the constructor should be in the constructor of the sub class.

Parameters:
startLabel - The label at which the program should start.
prio - The priority the program should start with.

EmbeddedSJProgram

public EmbeddedSJProgram(StateLabel startLabel,
                         int prio,
                         SJLogger myLogger)
The constructor to start a new SJ-program. Using this constructor should always be the first then you start a SJ-program. The normal place to use the constructor should be in the constructor of the sub class. To get the logging information about the program and process them you can use a logger.

Parameters:
startLabel - The label at which the program should start.
prio - The priority the program should start with.
myLogger - The logger to process the logging informations. If you set this to null there will be no logging.
Method Detail

getTickNr

public int getTickNr()
Returns the Number of the current tick. Every program starts with tick 0. If you use a method to go to the next tick the tick number will be increment.

Returns:
The number of the current tick. The method will return -1 if the program is in the initial tick.
See Also:
doTick(Signal...)

isInInitialTick

public boolean isInInitialTick()
Gives you a information if the program is in the initial tick and not has been started.

Returns:
Returns true if the program is in an initial tick else false.

isTerminated

public boolean isTerminated()
Tells us if a SJ program is terminated.

Returns:
true if the program is terminated else false.

isTickDone

public boolean isTickDone()
Return true if the current tick is Done. That means that every threads is either in a PAUSE statement (may hidden in a statement like await) or is Terminated. To run the next tick use doTick(Signal...).

Returns:
A boolean that is true if the current tick is done. Otherwise the boolean is false.
See Also:
doTick(Signal...), tick()

isThreadRunning

public boolean isThreadRunning()
Tells us if at the moment a thread is running.

Returns:
Returns true if a thread is running.

tick

public abstract void tick()
Function that should be implemented with a SJ-Program. It should contain the behaver of the program. Every time the method is called it should do exactly one tick an then terminate. Use this method only to override it if you want to execute a tick use doTick(Signal...)

See Also:
doTick(Signal...)

state

public StateLabel state()
Returns the next state (also called thread) to execute of a program. If all states are done or the program has terminated a runtime exception will be thrown. You should check this first.

Returns:
the next state to execute

addSignals

public void addSignals(Signal... declaredSignals)
Method to declare signal used by SJ. Declared signals are reseted automatically at the beginning of the next tick. You have to declare all signals you use in your ptogram.

Parameters:
declaredSignals - The signal you want to declare.

removeSignals

public void removeSignals(Signal... declaredSignals)
Removes signals and so undeclare them.

Parameters:
declaredSignals - The signals to remove

doTick

public Signal[] doTick(Signal... inputs)
Do a tick in the SJ program. Executes tick() and does all the management like incrementing the tick number and logging.

Parameters:
inputs - The input signals.
Returns:
All signals of the program with the status after executing the tick.

getSignals

public Signal[] getSignals()
Returns all signals known by the program.

Returns:
Returns the signals of the program.

getName

public String getName()
Returns the name of the program.

Returns:
The name of this program.

setLogger

public void setLogger(SJLogger myLogger)
Set the logger to log the JSON informations about the program. If you set the logger to the value null there will be no logging.

Parameters:
myLogger - The new logger.
See Also:
getLogger()

getLogger

public SJLogger getLogger()
Returns the logger used by this program. If this method returns null no logger is used.

Returns:
The current logger of the program.

activateCausalityCheck

public void activateCausalityCheck()
Activates the causality check for all signals of the program.


isCausalityCheckActive

public boolean isCausalityCheckActive()
Tells if the causality check is active.

Returns:
true if the check is active else false.

toString

public String toString()
Overrides:
toString in class Object

abort

public void abort()
Does a abort to all descendant created by the thread currently running. A descendant is created with fork(Enum, int) and forkEB(Enum).

See Also:
suspend()

awaitDoneCB

public boolean awaitDoneCB(Signal signal)
Waits for a signal after a initial pause. If the signal is present and a initial pause is already done this method will return true. Otherwise it will do a pause checked in the next tick again and return false. For the check of awaitDone in the next tick awaitDone has to be the first statement after a case so that we can return exactly to this statement in the next tick.

Parameters:
signal - the signal to check
Returns:
true if signal present and an initial pause done otherwise false

fork

public void fork(StateLabel label,
                 int prio)
Part of a Process to execute 2 Program parts in a simulated parallel way. This method adds a new thread to the list of threads to execute in this tick.

Parameters:
label - The label for the new thread created with fork.
prio - The priority for the new thread created with fork.

forkEB

public void forkEB(StateLabel label)
Ends a number of forks and says there this thread should continue after the forks. The B means we need a break after this command. The break should cause a new schedule. The name forkE stands for "fork end".

Parameters:
label - The label to continue after the forks.
See Also:
fork(Enum, int)

gotoB

public void gotoB(StateLabel label)
Goes to a label and continue with the code at this label. The classical jump or goto for this switch-case state-machine. Attention: The B in the method name means that after using this method you have to write a break; in your program.

Parameters:
label - The label to continue at.

haltCB

public void haltCB()
Halts at the current position.


joinDoneCB

public boolean joinDoneCB()
Joins threads by checking if all created descendants of the current thread are executed successful.

Returns:
A boolean value that tells if all in from the executing thread created descendants terminated.

pauseB

public void pauseB(StateLabel resumeLabel)
Stops the execution of the state in which it is used for the current tick. In the next tick this thread will continue at the label given as a parameter with the same priority. This has no effect on the execution of parallel threads. Attention: The B in the method name means that after using this method you have to write a break; in your program. Child threads are not destroyed by pause.

Parameters:
resumeLabel - - the label this thread will resume at in the next tick.

prioB

public void prioB(StateLabel label,
                  int prio)
Changes the priority of a thread and cause a new schedule. The thread with the highest priority will always execute at the next scheduling.

Parameters:
label - the label to continue at the next time executing this thread
prio - the new priority of this thread

suspend

public void suspend()
Suspends all descendants threads of the current thread.

See Also:
abort()

termB

public void termB()
Terminates the current Thread. This execution should always be used if all execution of the thread are done. Attention: The B in the method name means that after using this method you have to write a break; in your program.


transB

public void transB(StateLabel label)
Aborts all descendants and their descendants of the executing thread. After that the scheduler is advised to go to the given label next time state() is used. This method is a shorthand for abort() + gotoB(Enum).

Parameters:
label - the label to go to
See Also:
abort(), gotoB(Enum)