se.lth.cs.realtime
Class RTThread

java.lang.Object
  |
  +--se.lth.cs.realtime.RTThread

All Implemented Interfaces:

java.util.EventListener, RTEventListener

Direct Known Subclasses:

CyclicThread, OngoingThread

public abstract class RTThread

extends java.lang.Object

implements RTEventListener

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 whould have been called, the ser is supposed to retrieve the RTThread object to gain full support for embedded applications.

See Also:

Thread, FixedPriority, RTThreadGroup

Field Summary

protected int	defaultEventBufferSize Default size of the event buffer, used by constructor possibly after being changed by some subclass constructor.
protected RTEventListenerList	listenerList The list of the listeners of this thread.
protected RTEventBuffer	mailbox The event inbut buffer.
static int	MAX_PRIORITY The maximum priority that a thread can have.
static int	MIN_PRIORITY The minimum 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.

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

static RTThread	currentRTThread() Returns a reference to the currently executing RTThread object.
static void	dumpStack() Prints a stack trace of the current thread.
java.lang.String	getName() Returns this thread's name.
int	getPriority() Returns this thread's priority.
RTThreadGroup	getRTThreadGroup() Returns this thread's RTThreadGroup.
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.
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.
void	putEvent(RTEvent ev) Put the time-stamped event in the input buffer of this thread.
protected abstract void	run() Corresponds to java.lang.Thread.run and has the same semantics.
void	setDaemon(boolean on) Marks this thread as either a daemon thread or a user thread.
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) Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.
static void	sleep(long millis, int nanos) Causes the currently executing thread to sleep (cease execution) for the specified number of milliseconds plus the specified number of nanoseconds.
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.
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

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

Field Detail

mailbox

protected RTEventBuffer mailbox

The event inbut buffer.

defaultEventBufferSize

protected int defaultEventBufferSize

Default size of the event buffer, used by constructor possibly after being changed by some subclass constructor.

listenerList

protected RTEventListenerList listenerList

The list of the listeners of this thread.

See Also:

RTEventListenerList

MIN_PRIORITY

public static final int MIN_PRIORITY

The minimum priority that a thread can have.

MAX_PRIORITY

public static final int MAX_PRIORITY

The maximum priority that a thread can have.

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

putEvent

public void 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

Following copied from interface: se.lth.cs.realtime.event.RTEventListener

Parameters:

e - Event to handle

currentRTThread

public static RTThread currentRTThread()

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

Returns:

the currently executing real-time thread.

yield

public static void yield()

Causes the currently executing thread object to temporarily pause and allow other threads to execute.

sleepUntil

public static void sleepUntil(long wakeUpTime)
                       throws java.lang.InterruptedException

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:

java.lang.InterruptedException - if another thread has interrupted this thread.

sleep

public static void sleep(long millis)
                  throws java.lang.InterruptedException

Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. The thread does not lose ownership of any monitors.

Parameters:

millis - the length of time to sleep in milliseconds.

Throws:

java.lang.IllegalArgumentException - if the value of millis is negative.

java.lang.InterruptedException - if another thread has interrupted this thread.

See Also:

Object.notify()

sleep

public static void sleep(long millis,
                         int nanos)
                  throws java.lang.InterruptedException

Causes the currently executing thread to sleep (cease execution) for the specified number of milliseconds plus the specified number of nanoseconds. The thread does not lose ownership of any monitors.

Parameters:

millis - the length of time to sleep in milliseconds.

nanos - 0-999999 additional nanoseconds to sleep.

Throws:

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

java.lang.InterruptedException - if another thread has interrupted this thread.

See Also:

Object.notify()

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

Throws:

IllegalThreadStateException - if the thread was already started.

See Also:

run()

run

protected abstract void run()

Corresponds to java.lang.Thread.run and has the same semantics.

See Also:

Thread.run(), start()

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. the "interruption-flag" is not modified.

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.

Returns:

true if this thread is alive; false otherwise.

setPriority

public final void setPriority(int newPriority)
                       throws FixedPriorityException

Changes the priority of this thread.

If this thread implements the FixedPriority interface and is alive, an exception is thrown.

Throws:

FixedPriorityException - If this thread is declared to implement the FixedPriority interface and is alive.

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()

Returns this thread's priority.

Returns:

this thread's name.

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)

getRTThreadGroup

public final RTThreadGroup getRTThreadGroup()

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

Throws:

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

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:

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)

toString

public java.lang.String toString()

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

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this thread.