se.lth.cs.realtime
Class RTThread

java.lang.Object
  se.lth.cs.realtime.RTThread

All Implemented Interfaces:

Activity, java.util.EventListener, RTEventListener, RTEventSource

Direct Known Subclasses:

CyclicThread, OngoingThread

public abstract class RTThread

extends java.lang.Object

implements Activity, RTEventListener, RTEventSource

This class defines a thread of execution in a real-time environment.

A normal java.lang.Thread is not suitable to real-time problems since it does not provide primitives like sleepUntil(), necessary to implement periodic real-time processes properly, while, conversely, it provides means to asynchronously change the priority of a thread which sometimes is not acceptable. Since some methods of java.lang.Thread are declared final, subclassing java.lang.Thread is not a solution.

Every real-time thread has a priority (if FixedPriority is implemented, it can be modified only before starting the thread); each thread may or may not also be marked as a daemon. When code run by some thread creates a new RTThread object, the new thread has its priority initially set equal to the priority of the creating thread, and it is set to be a daemon thread if and only if the creating thread is a daemon.

Every RTThread belongs to a RTThreadGroup.

Every thread has a name for identification purposes. More than one thread may have the same name. If a name is not specified when a thread is created, a new name is generated for it. The user may of course call Thread.currentThread to obtain the java.lang.Thread which is encapsulated by the RTThread object, and, for instance, calling interrupt on that object will work as if the interrupt of RTThread would have been called, the user is supposed to retrieve the RTThread object to gain full support for embedded applications.

See Also:

License, Thread, FixedPriority, RTThreadGroup

Field Summary

static int	MAX_PRIORITY The maximum priority that a thread can have.
static int	MIN_PRIORITY The minimum priority that a thread can have.
static int	NORM_PRIORITY The maximum priority that a thread can have.

Constructor Summary

RTThread()
Allocates a new RTThread object with a newly generated name in its father's RTThreadGroup.

RTThread(RTThreadGroup group)
Allocates a new RTThread object with a newly generated name in the specified RTThreadGroup.

RTThread(RTThreadGroup group, java.lang.String name)
Allocates a new RTThread object with the specified name in the specified RTThreadGroup.

RTThread(java.lang.String name)
Allocates a new RTThread object with the specified name in its father's RTThreadGroup.

Method Summary

void	addListener(RTEventListener subscriber) Subscribe on RTEvents from this source.
static RTThread	currentRTThread() Returns a reference to the currently executing RTThread.
static java.lang.Object	currentThread() Returns a reference to the currently executing thread object, which can be either an RTThread or a java.lang.Thread.
static void	dumpStack() Prints a stack trace of the current thread.
RTEventDispatcher	getDispatcher() Obtain the object that internally stores the subscriptions of events, often referred to as the listener list.
Environment	getEnv() Environments not implemented yet.
int	getMaxTimeLag()
java.lang.String	getName() Returns this thread's name.
int	getPriority() Obtain the priority of this thread.
int	getRTThreadId() Obtain the unique RTThread number assigned to this thread object.
RTThreadGroup	getThreadGroup() Returns this thread's RTThreadGroup.
Timebase	getTimebase() Time bases not implemented yet.
void	interrupt() Interrupts this thread.
static boolean	interrupted() Tests if the current thread has been interrupted.
boolean	isAlive() Tests if this thread is alive.
boolean	isDaemon() Tests if this thread is a daemon thread.
boolean	isInterrupted() Tests if this thread has been interrupted without modifying the "interruption-flag".
void	join() Waits for this thread to die.
void	join(long millis) Waits at most millis milliseconds for this thread to die.
void	join(long millis, int nanos) Waits at most millis milliseconds plus nanos nanoseconds for this thread to die.
RTEvent	putEvent(RTEvent ev) Put the time-stamped event in the input buffer of this thread.
void	setDaemon(boolean on) Marks this thread as either a daemon thread or a user thread.
void	setMaxTimeLag(int maxResponseTime)
void	setName(java.lang.String name) Changes the name of this thread to be equal to the argument name.
void	setPriority(int newPriority) Changes the priority of this thread.
static void	sleep(long millis) Sleep for (at least) millis ms, handled by RTSystem.
static void	sleep(long millis, int nanos) Sleep for (at least) millis ms plus nanos ns, handled by RTSystem.
static void	sleepUntil(long wakeUpTime) Causes the currently executing thread to sleep (temporarily cease execution) until the specified moment in time.
void	start() Causes this thread to begin execution.
void	terminate() Interrupt and join.
java.lang.String	toString() Returns a string representation of this thread, including the thread's name and priority.
static void	yield() Causes the currently executing thread object to temporarily pause and allow other threads to execute.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MIN_PRIORITY

public static final int MIN_PRIORITY

The minimum priority that a thread can have.

See Also:

Constant Field Values

MAX_PRIORITY

public static final int MAX_PRIORITY

The maximum priority that a thread can have.

See Also:

Constant Field Values

NORM_PRIORITY

public static final int NORM_PRIORITY

The maximum priority that a thread can have.

See Also:

Constant Field Values

Constructor Detail

RTThread

public RTThread()

Allocates a new RTThread object with a newly generated name in its father's RTThreadGroup. Automatically generated names are of the form "RTThread-"+ n , where n is an integer.

RTThread

public RTThread(java.lang.String name)

Allocates a new RTThread object with the specified name in its father's RTThreadGroup.

Parameters:

name - the name of the new thread.

RTThread

public RTThread(RTThreadGroup group)

Allocates a new RTThread object with a newly generated name in the specified RTThreadGroup.

Automatically generated names are of the form "RTThread-"+ n , where n is an integer.

Parameters:

group - the RTThreadGroup of the new thread.

RTThread

public RTThread(RTThreadGroup group,
                java.lang.String name)

Allocates a new RTThread object with the specified name in the specified RTThreadGroup.

Parameters:

name - the name of the new thread.

group - the RTThreadGroup of the new thread.

Method Detail

setMaxTimeLag

public void setMaxTimeLag(int maxResponseTime)

getMaxTimeLag

public int getMaxTimeLag()

getRTThreadId

public int getRTThreadId()

Obtain the unique RTThread number assigned to this thread object. When a new thread object is created

Returns:

Returns the number of this object

putEvent

public RTEvent putEvent(RTEvent ev)

Put the time-stamped event in the input buffer of this thread. If the buffer is full, the caller is blocked.

Specified by:

putEvent in interface RTEventListener

Parameters:

ev - Event to process or buffer for processing

Returns:

null, but subclasses are free to return an event if desired to inform about blocking or results.

getDispatcher

public RTEventDispatcher getDispatcher()

Obtain the object that internally stores the subscriptions of events, often referred to as the listener list. Opposed to listener lists in GUI packages (such as AWT and Swing), where the listener typically gets its processing method called and fully performed in the context of the GUI thread, the subscribers/listeners of RTEvent s gets a call of putEvent which typically only stores/buffers the event for later processing by the receiving thread (object). Thus, the EventSource simply dispatches the event distribution, hence the name dispatcher of the lister list storage object.

Specified by:

getDispatcher in interface RTEventSource

Returns:

the object providing registration of RTEvent listeners. The returned dispatcher corresponds to the javax.swing.event.EventListenerList, but enhanced for real-time usage.

addListener

public void addListener(RTEventListener subscriber)

Description copied from interface: RTEventSource

Subscribe on RTEvents from this source.

Specified by:

addListener in interface RTEventSource

Parameters:

subscriber - the object interested in getting the events via its putEvent method.

currentRTThread

public static RTThread currentRTThread()

Returns a reference to the currently executing RTThread. If the currently executing thread is not an RTThread, null is returned.

Returns:

the currently executing real-time thread.

currentThread

public static java.lang.Object currentThread()

Returns a reference to the currently executing thread object, which can be either an RTThread or a java.lang.Thread. Since those two types of threads do not share a common thread base class, the return type is Object.

Returns:

the currently executing thread.

yield

public static final void yield()

Causes the currently executing thread object to temporarily pause and allow other threads to execute. If the currently executing thread is a java.lang.Thread,yield of that class is called.

sleepUntil

public static void sleepUntil(long wakeUpTime)
                       throws RTInterrupted,
                              RTDelayed

Causes the currently executing thread to sleep (temporarily cease execution) until the specified moment in time. Time is measured in milliseconds, starting from 00am, January 1st 1970, UTC. The thread does not lose ownership of any monitors.

Parameters:

wakeUpTime - the time to wake up.

Throws:

RTInterrupted - if another thread has interrupted this thread.

RTDelayed - if execution continues more than maxTimeLag too late.

sleep

public static void sleep(long millis)
                  throws RTInterrupted,
                         RTDelayed

Sleep for (at least) millis ms, handled by RTSystem.

Throws:

RTInterrupted

RTDelayed

See Also:

RTSystem.sleep(long)

sleep

public static void sleep(long millis,
                         int nanos)
                  throws RTInterrupted,
                         RTDelayed

Sleep for (at least) millis ms plus nanos ns, handled by RTSystem.

Throws:

RTInterrupted

RTDelayed

See Also:

RTSystem.sleep(long,int)

start

public void start()

Causes this thread to begin execution.

The result is that two threads are running concurrently: the current thread (which returns from the call to the start method) and the other thread (which executes its run method).

Specified by:

start in interface Activity

Throws:

java.lang.IllegalThreadStateException - if the thread was already started.

See Also:

RTThread#run()

interrupt

public void interrupt()

Interrupts this thread. Thus an "interruption-flag" is set, which may raise an InterruptedException in the interrupted thread; otherwise the flag can be checked via interrupted or isInterrupted.

See Also:

interrupted(), isInterrupted()

interrupted

public static boolean interrupted()

Tests if the current thread has been interrupted. The "interruption-flag" is reset.

Note that interrupted is a static method, while isInterrupted is called on this Thread instance.

Returns:

true if the current thread has been interrupted; false otherwise.

See Also:

interrupt(), isInterrupted()

isInterrupted

public boolean isInterrupted()

Tests if this thread has been interrupted without modifying the "interruption-flag".

Note that isInterrupted is called on this RTThread instance; by contrast, interrupted is a static method.

Returns:

true if this thread has been interrupted; false otherwise.

See Also:

interrupt(), interrupted()

isAlive

public final boolean isAlive()

Tests if this thread is alive. A thread is alive if it has been started and has not yet died.

Specified by:

isAlive in interface Activity

Returns:

true if this thread is alive; false otherwise.

setPriority

public final void setPriority(int newPriority)
                       throws FixedPriorityError

Changes the priority of this thread.

Throws:

FixedPriorityError - If this thread is alive and implements the FixedPriority interface.

java.lang.IllegalArgumentException - If the priority is not in the range MIN_PRIORITY to MAX_PRIORITY.

See Also:

getPriority(), FixedPriority

getPriority

public final int getPriority()

Obtain the priority of this thread.

Returns:

this thread's priority.

See Also:

setPriority(int)

setName

public final void setName(java.lang.String name)

Changes the name of this thread to be equal to the argument name.

Parameters:

name - the new name for this thread.

See Also:

getName()

getName

public final java.lang.String getName()

Returns this thread's name.

Returns:

this thread's name.

See Also:

setName(java.lang.String)

getThreadGroup

public final RTThreadGroup getThreadGroup()

Returns this thread's RTThreadGroup.

Returns:

this thread's RTThreadGroup.

join

public final void join(long millis)
                throws java.lang.InterruptedException

Waits at most millis milliseconds for this thread to die. A timeout of 0 means to wait forever. A CyclicThread is not allowed to join another thread. (TO FIX)

Parameters:

millis - the time to wait in milliseconds.

Throws:

java.lang.InterruptedException - if another thread has interrupted the current thread.

java.lang.IllegalStateException - if the calling thread is an instance of CyclicRTThread .

See Also:

CyclicThread

join

public final void join(long millis,
                       int nanos)
                throws java.lang.InterruptedException

Waits at most millis milliseconds plus nanos nanoseconds for this thread to die.

Parameters:

millis - the time to wait in milliseconds.

nanos - 0-999999 additional nanoseconds to wait.

Throws:

java.lang.IllegalArgumentException - if the value of millis is negative the value of nanos is not in the range 0-999999.

java.lang.InterruptedException - if another thread has interrupted the current thread.

join

public final void join()
                throws java.lang.InterruptedException

Waits for this thread to die.

Specified by:

join in interface Activity

Throws:

java.lang.InterruptedException - if another thread has interrupted the current thread.

terminate

public void terminate()

Interrupt and join.

Specified by:

terminate in interface Activity

dumpStack

public static void dumpStack()

Prints a stack trace of the current thread. This method is used only for debugging.

See Also:

Throwable.printStackTrace()

setDaemon

public final void setDaemon(boolean on)

Marks this thread as either a daemon thread or a user thread.

This method must be called before the thread is started.

Parameters:

on - if true, marks this thread as a daemon thread.

Throws:

java.lang.IllegalThreadStateException - if this thread is active.

See Also:

isDaemon()

isDaemon

public final boolean isDaemon()

Tests if this thread is a daemon thread.

Returns:

true if this thread is a daemon thread; false otherwise.

See Also:

setDaemon(boolean)

getTimebase

public Timebase getTimebase()

Time bases not implemented yet.

Specified by:

getTimebase in interface Activity

Returns:

null.

getEnv

public Environment getEnv()

Environments not implemented yet.

Specified by:

getEnv in interface Activity

Returns:

null.

toString

public java.lang.String toString()

Returns a string representation of this thread, including the thread's name and priority.

Returns:

a string representation of this thread.