pt.ua.concurrent

Class CThread

java.lang.Object

java.lang.Thread

pt.ua.concurrent.CThread

All Implemented Interfaces:

java.lang.Runnable

public class CThread
extends java.lang.Thread

Thread related static utilities.

This class follows DbC(tm) methodology (Wikipedia). Where possible, contracts are implement with native's Java assert.

Version:

0.6, October 2013

Author:

Miguel Oliveira e Silva (mos@ua.pt)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CThread.TerminationPolicy Termination policy for thread created through current CThread's object.

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
CThread() Constructor of a thread (direct replacement of Thread's constructor).
CThread(CRunnable ctarget) Constructor of a thread (direct replacement of Thread's constructor).
CThread(CRunnable ctarget, java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.Runnable target) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.Runnable target, java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, CRunnable ctarget) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, CRunnable ctarget, java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, CRunnable ctarget, java.lang.String name, long stackSize) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, java.lang.Runnable target) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, java.lang.Runnable target, java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, java.lang.Runnable target, java.lang.String name, long stackSize) Constructor of a thread (direct replacement of Thread's constructor).
CThread(java.lang.ThreadGroup group, java.lang.String name) Constructor of a thread (direct replacement of Thread's constructor).

Method Summary

Modifier and Type	Method and Description
void	ajoin() Thread's join replacement, in which: - the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.
void	ajoin(long millis) Thread's join replacement, in which: - the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.
void	ajoin(long millis, int nanos) Thread's join replacement, in which: - the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.
void	arun() The new thread program method.
static java.lang.Thread	currentThread() Current thread.
static long	currentThreadID() Current thread id.
long	elapsedTime() Elapsed time since startTime.
boolean	failed() Did thread failed (terminated with an exception) its execution? Precondition: terminated()
static void	pause(int millis) A thread safe pause service in which: - the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.
void	run() Replacement of default run method to correctly handle exceptions, and also to register thread execution start time.
void	setTerminationPolicy(CThread.TerminationPolicy terminationPolicy) Define the thread's termination policy.
java.lang.Throwable	sourceException() Get the exception responsible for the thread's failure.
void	start() Replacement of default start method (required to properly implement termination policy).
void	start(CThread.TerminationPolicy terminationPolicy) A start method imposing an explicit termination policy.
boolean	started() Was request to start thread issued?
long	startTime() Time instance at which the thread has started execution.
boolean	startTimeRegistered() Has thread start time been registered?
boolean	terminated() Thread terminated?
CThread.TerminationPolicy	terminationPolicy() Current CThread object's termination policy.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

CThread

public CThread()

Constructor of a thread (direct replacement of Thread's constructor).

CThread

public CThread(java.lang.Runnable target)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

target != null - Runnable object reference

Parameters:

target - Runnable to attach to thread

CThread

public CThread(java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

name != null - String object reference

Parameters:

name - String ID to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

name != null - String object reference

Parameters:

group - thread's ThreadGroup

name - String ID to attach to thread

CThread

public CThread(java.lang.Runnable target,
               java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

target != null - Runnable object reference

name != null - String object reference

Parameters:

target - Runnable to attach to thread

name - String ID to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               java.lang.Runnable target)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - Runnable object reference

Parameters:

group - thread's ThreadGroup

target - Runnable to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               java.lang.Runnable target,
               java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - Runnable object reference

name != null - String object reference

Parameters:

group - thread's ThreadGroup

target - Runnable to attach to thread

name - String ID to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               java.lang.Runnable target,
               java.lang.String name,
               long stackSize)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - Runnable object reference

name != null - String object reference

stackSize > 0L - positive stack size

Parameters:

group - thread's ThreadGroup

target - Runnable to attach to thread

name - String ID to attach to thread

stackSize - future thread's stack size

CThread

public CThread(CRunnable ctarget)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

target != null - CRunnable object reference

Parameters:

ctarget - CRunnable to attach to thread

CThread

public CThread(CRunnable ctarget,
               java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

target != null - CRunnable object reference

name != null - String object reference

Parameters:

ctarget - CRunnable to attach to thread

name - String ID to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               CRunnable ctarget)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - CRunnable object reference

Parameters:

group - thread's ThreadGroup

ctarget - CRunnable to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               CRunnable ctarget,
               java.lang.String name)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - CRunnable object reference

name != null - String object reference

Parameters:

group - thread's ThreadGroup

ctarget - CRunnable to attach to thread

name - String ID to attach to thread

CThread

public CThread(java.lang.ThreadGroup group,
               CRunnable ctarget,
               java.lang.String name,
               long stackSize)

Constructor of a thread (direct replacement of Thread's constructor).

Precondition:

group != null - ThreadGroup object reference

target != null - CRunnable object reference

name != null - String object reference

stackSize > 0L - positive stack size

Parameters:

group - thread's ThreadGroup

ctarget - CRunnable to attach to thread

name - String ID to attach to thread

stackSize - future thread's stack size

Method Detail

setTerminationPolicy

public void setTerminationPolicy(CThread.TerminationPolicy terminationPolicy)

Define the thread's termination policy. Four options are available:

• TerminationPolicy.DEBUG: a thread failure causes a stack dump and the termination of the whole program (default behavior)
• TerminationPolicy.PROPAGATE: a thread failure causes the propagation of the failure to the ``parent'' thread (through the interrupt service)
• TerminationPolicy.IGNORE: a thread failure is ignored for the whole program
• TerminationPolicy.IGNORE_DEBUG: stack dumped to console, but thread failure is ignored for the whole program

Precondition:

!started()

Parameters:

terminationPolicy - policy (TerminationPolicy.DEBUG, TerminationPolicy.PROPAGATE, TerminationPolicy.IGNORE, TerminationPolicy.IGNORE_DEBUG)

terminationPolicy

public CThread.TerminationPolicy terminationPolicy()

Current CThread object's termination policy.

Returns:

current termination policy

start

public void start(CThread.TerminationPolicy terminationPolicy)

A start method imposing an explicit termination policy.

Precondition:

!started()

Parameters:

terminationPolicy - policy (TerminationPolicy.DEBUG, TerminationPolicy.PROPAGATE, TerminationPolicy.IGNORE, TerminationPolicy.IGNORE_DEBUG)

See Also:

setTerminationPolicy

start

public void start()

Replacement of default start method (required to properly implement termination policy).

Precondition:

!started()

Overrides:

start in class java.lang.Thread

started

public boolean started()

Was request to start thread issued?

Returns:

true, if request issued

terminated

public boolean terminated()

Thread terminated?

Returns:

true, if terminated

failed

public boolean failed()

Did thread failed (terminated with an exception) its execution?

Precondition:

terminated()

Returns:

true, if thread failed

sourceException

public java.lang.Throwable sourceException()

Get the exception responsible for the thread's failure.

Precondition:

terminated() && failed() && terminationPolicy() == TerminationPolicy.PROPAGATE

Returns:

the exception

run

public void run()

Replacement of default run method to correctly handle exceptions, and also to register thread execution start time. The thread program must be defined in arun method.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

arun

public void arun()

The new thread program method.

startTimeRegistered

public boolean startTimeRegistered()

Has thread start time been registered?

Returns:

true, if time registered

startTime

public long startTime()

Time instance at which the thread has started execution. Requires the usage of arun method either through CThread or CRunnable.

Precondition:

startTimeRegistered()

Returns:

time value

elapsedTime

public long elapsedTime()

Elapsed time since startTime.

Precondition:

startTimeRegistered()

Returns:

time value

ajoin

public void ajoin()
           throws ThreadInterruptedException

Thread's join replacement, in which:
- the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.

Throws:

ThreadInterruptedException

ajoin

public void ajoin(long millis)
           throws ThreadInterruptedException

Thread's join replacement, in which:
- the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.

Precondition:

millis >= 0 - non negative timeout

Parameters:

millis - timeout (in milliseconds)

Throws:

ThreadInterruptedException

ajoin

public void ajoin(long millis,
                  int nanos)
           throws ThreadInterruptedException

Thread's join replacement, in which:
- the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.

Precondition:

millis >= 0 - non negative timeout

nanos >= 0 - non negative timeout

Parameters:

millis - timeout (in milliseconds)

nanos - timeout (in nanoseconds)

Throws:

ThreadInterruptedException

pause

public static void pause(int millis)
                  throws ThreadInterruptedException

A thread safe pause service in which:
- the checked exception InterruptedException, is replaced by the unchecked exception ThreadInterruptedException.

Precondition:

millis >= 0 - non negative pause value

Parameters:

millis - pause value (in milliseconds)

Throws:

ThreadInterruptedException

currentThread

public static java.lang.Thread currentThread()

Current thread.

Returns:

the Thread object

currentThreadID

public static long currentThreadID()

Current thread id.

Returns:

the thread id