javax.realtime

Class RealtimeThread

java.lang.Object

java.lang.Thread

javax.realtime.RealtimeThread

All Implemented Interfaces:

java.lang.Runnable, AsyncTimable, BoundSchedulable, Releasable<Timable,TimeDispatcher>, Schedulable, Timable

Direct Known Subclasses:

NoHeapRealtimeThread

public class RealtimeThread
extends java.lang.Thread
implements BoundSchedulable, AsyncTimable

Jamaica Real-Time Specification for Java class RealtimeThread.

Threads of class RealtimeThread that are scheduled by the default PriorityScheduler can use an additional range of priorities that are higher than the priorities of normal Java threads.

Threads of class RealtimeThread that are allocated in scoped memory (any memory area that is not HeapMemory or ImmortalMemory) are not member of any thread group, the result of Thread.getThreadGroup() will be null for these threads.

Nested Class Summary

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
RealtimeThread() Constructor to create a RealtimeThread with default parameters as in RealtimeThread(null, null, null, null, null, null).
RealtimeThread(SchedulingParameters scheduling) Constructor to create a RealtimeThread using specified scheduling parameters and default values for all other parameters.
RealtimeThread(SchedulingParameters scheduling, ReleaseParameters release) Constructor to create a RealtimeThread using specified scheduling and release parameters and default values for all other parameters.
RealtimeThread(SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, MemoryArea area, ConfigurationParameters config, TimeDispatcher dispatcher, RealtimeThreadGroup group, java.lang.Runnable logic) Creates a realtime thread with the given characteristics and a specified Runnable.
RealtimeThread(SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, MemoryArea area, ProcessingGroupParameters group, java.lang.Runnable logic) Constructor to create a RealtimeThread using specified scheduling, release, and memory parameters, using the specified memory area, group, and logic.

Method Summary

Modifier and Type	Method and Description
boolean	addIfFeasible() addIfFeasible adds this to the feasibility analysis of the associated scheduler if the resulting system will be feasible.
boolean	addToFeasibility() addToFeasibility notifies the scheduler associated with this that this schedulable object's scheduling, release, memory, and processing group parameters take part in the feasibility analysis.
static RealtimeThread	currentRealtimeThread() currentRealtimeThread returns a reference to the current RealtimeThread.
void	deschedulePeriodic() deschedulePeriodic deschedules this thread if its release parameters are PeriodicParameters.
void	fire() Called by the dispatcher associated with this to indicate that a time event has occured.
static MemoryArea	getCurrentMemoryArea() Get the memory area that the calling Schedulable object has for its allocation context.
TimeDispatcher	getDispatcher() Gets the dispatcher associated with this Timable.
static int	getInitialMemoryAreaIndex() getInitialMemoryAreaIndex returns the index of the current RealtimeThread's or AsyncBaseEventHandler's initial memory area.
MemoryArea	getMemoryArea() getMemoryArea returns the initial memory area provided to the constructor of this thread.
static int	getMemoryAreaStackDepth() getMemoryAreaStackDepth returns the current size of the stack of entered memory areas of the current thread.
MemoryParameters	getMemoryParameters() getMemoryParameters returns a reference to the MemoryParameters of this RealtimeThread.
static MemoryArea	getOuterMemoryArea(int index) getOuterMemoryArea returns the MemoryArea in the stack of entered memory areas at the given index.
ProcessingGroupParameters	getProcessingGroupParameters() getProcessingGroupParameters returns the current ProcessingGroupParameters of this RealtimeThread.
ReleaseParameters	getReleaseParameters() getReleaseParameters returns the current ReleaseParameters of this RealtimeThread.
Scheduler	getScheduler() getScheduler returns the current scheduler of this RealtimeThread.
SchedulingParameters	getSchedulingParameters() getSchedulingParameters returns the SchedulingParameters of this RealtimeThread.
void	interrupt() interrupt causes a generic AsynchronouslyInterruptedException to be thrown in this RealtimeThread.
void	release() Increase the release count of the current realtime thread.
boolean	removeFromFeasibility() removeFromFeasibility informs the scheduler associated with this RealtimeThread that this RealtimeThread should no longer be taken into account in the feasibility analysis.
void	run() run contains only a call to logic.run if logic is not null.
void	schedulePeriodic() schedulePeriodic resumes the execution of a periodic thread, i.e., unblocks waitForNextPeriod.
boolean	setIfFeasible(ReleaseParameters release, MemoryParameters memory) setIfFeasible performs a feasibility analysis using the provided release and memory parameters.
boolean	setIfFeasible(ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group) setIfFeasible performs a feasibility analysis using the provided release, memory, and processing group parameters.
boolean	setIfFeasible(ReleaseParameters release, ProcessingGroupParameters group) setIfFeasible performs a feasibility analysis using the provided release and processing group parameters.
boolean	setIfFeasible(SchedulingParameters sched, ReleaseParameters release, MemoryParameters memory) setIfFeasible performs a feasibility analysis using the provided scheduling, release, and memory parameters.
boolean	setIfFeasible(SchedulingParameters sched, ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group) setIfFeasible performs a feasibility analysis using the provided scheduling, release, memory, and processing group parameters.
RealtimeThread	setMemoryParameters(MemoryParameters memory) setMemoryParameters replaces the memory parameters for this RealtimeThread with the parameters provided.
boolean	setMemoryParametersIfFeasible(MemoryParameters memory) setMemoryParametersIfFeasible performs a feasibility analysis using the provided memory parameters.
void	setProcessingGroupParameters(ProcessingGroupParameters group) setProcessingGroupParameters sets the processing group parameters of this thread.
boolean	setProcessingGroupParametersIfFeasible(ProcessingGroupParameters group) setProcessingGroupParametersIfFeasible performs a feasibility analysis using the provided processing group parameters.
RealtimeThread	setReleaseParameters(ReleaseParameters release) setReleaseParameters replaces the release parameters for this RealtimeThread with the parameters provided.
boolean	setReleaseParametersIfFeasible(ReleaseParameters release) setReleaseParametersIfFeasible performs a feasibility analysis using the provided release parameters.
RealtimeThread	setScheduler(Scheduler scheduler) setScheduler sets the scheduler for this RealtimeThread.
void	setScheduler(Scheduler scheduler, SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group) setScheduler set the scheduler and scheduling, release, memory, and processing group parameters for this RealtimeThread.
RealtimeThread	setSchedulingParameters(SchedulingParameters scheduling) setSchedulingParameters sets the scheduling parameters for this RealtimeThread.
boolean	setSchedulingParametersIfFeasible(SchedulingParameters scheduling) setSchedulingParametersIfFeasible performs a feasibility analysis using the provided scheduling parameters.
static void	sleep(Clock clock, HighResolutionTime<?> time) Sleep for a given relative or absolute time using the given clock.
static void	sleep(HighResolutionTime<?> time) Sleep for a given relative or absolute time using the clock associated with time.
void	start() start starts this RealtimeThread.
void	startPeriodic(PhasingPolicy policy) Starts a periodic thread with the specified phasing policy.
static boolean	waitForNextPeriod() waitForNextPeriod delays the current periodic thread until the beginning of the next period.
static boolean	waitForNextPeriodInterruptible() waitForNextPeriodInterruptible is an exact copy of waitForNextPeriod, but permits to be interrupted when waiting for the next period or when waiting for a call to schedulePeriodic().
static boolean	waitForNextRelease() Block the current realtime thread until the beginning of the next period or a call to its release() method.
static boolean	waitForNextReleaseInterruptible() Same as waitForNextRelease() except it can throw an interrupted exception

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, 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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RealtimeThread

public RealtimeThread()

Constructor to create a RealtimeThread with default parameters as in RealtimeThread(null, null, null, null, null, null).

RealtimeThread

public RealtimeThread(SchedulingParameters scheduling)

Constructor to create a RealtimeThread using specified scheduling parameters and default values for all other parameters. This is equivalent to RealtimeThread(scheduling, null, null, null, null, null);

Parameters:

scheduling - SchedulingParameters to be associated with the new thread. This can be shared with several Schedulable objects. If it is null, a copy of the creator's value will be created in the same memory area as this RealtimeThread object. If it is null and the current thread is a normal Java thread, the scheduling parameters will be set to the default priority.

Throws:

StaticIllegalArgumentException - iff scheduling parameters are not compatible with the default scheduler, i.e., iff they are non-null and not an instance of PriorityParameters.

IllegalAssignmentError - if scheduling and this reside in memory areas whose objects cannot refer to one another (in both directions).

RealtimeThread

public RealtimeThread(SchedulingParameters scheduling,
                      ReleaseParameters release)

Constructor to create a RealtimeThread using specified scheduling and release parameters and default values for all other parameters. This is equivalent to RealtimeThread(scheduling, release, null, null, null, null);

Parameters:

scheduling - SchedulingParameters to be associated with the new thread. This can be shared with several Schedulable objects. If it is null, a copy of the creator's value will be created in the same memory area as this RealtimeThread object. If it is null and the current thread is a normal Java thread, the scheduling parameters will be set to the default priority.

release - ReleaseParameters to be associated with the new thread. This can be shared with several Schedulable objects. If it is null, default release parameters will be used.

Throws:

StaticIllegalArgumentException - iff scheduling or release parameters are not compatible with the default scheduler, i.e., iff they are non-null and not an instance of PriorityParameters or PeriodicParameters, AperidodicParameters and SporadicParameters, respectively.

IllegalAssignmentError - if scheduling or release and this reside in memory areas whose objects cannot refer to one another (in both directions).

RealtimeThread

public RealtimeThread(SchedulingParameters scheduling,
                      ReleaseParameters release,
                      MemoryParameters memory,
                      MemoryArea area,
                      ProcessingGroupParameters group,
                      java.lang.Runnable logic)

Constructor to create a RealtimeThread using specified scheduling, release, and memory parameters, using the specified memory area, group, and logic.

If group is null, the thread group is inherited from the creating thread unless this RealtimeThread object resides in ScopedMemory. In this case, the thread group will be set to null.

Parameters:

scheduling - SchedulingParameters to be associated with the new thread. This can be shared with several Schedulable objects. If it is null, a copy of the creator's value will be created in the same memory area as this RealtimeThread object. If it is null and the current thread is a normal Java thread, the scheduling parameters will be set to the default priority.

release - ReleaseParameters to be associated with the new thread. This can be shared with several Schedulable objects. If it is null, default release parameters will be used.

memory - MemoryParameters to be associated with the new thread. May be null for unrestricted amount and rate of memory allocation for the new thread.

area - MemoryArea to be used by the new thread. If it is null, the current memory area of the calling thread will be used.

group - ProcessingGroupParameters to be associated with this. This can be shared with several Schedulable objects. If it is null, this will not be associated with any processing group.

logic - Runnable to be used as the logic for this. If it is null, the run() method in this new RealtimeThread object will be called when the thread is started.

Throws:

StaticIllegalArgumentException - iff scheduling or release parameters are not compatible with the default scheduler, i.e., iff they are non-null and not an instance of PriorityParameters or PeriodicParameters, AperidodicParameters and SporadicParameters, respectively.

IllegalAssignmentError - if scheduling, release, memory, area, group, or logic reside in memory areas whose objects cannot be referred to by this or this object resides in a memory area that cannot be referenced by scheduling, release, or memory.

RealtimeThread

public RealtimeThread(SchedulingParameters scheduling,
                      ReleaseParameters release,
                      MemoryParameters memory,
                      MemoryArea area,
                      ConfigurationParameters config,
                      TimeDispatcher dispatcher,
                      RealtimeThreadGroup group,
                      java.lang.Runnable logic)

Creates a realtime thread with the given characteristics and a specified Runnable. The realtime thread group of the new thread is inherited from its parent task unless group is set. The newly-created realtime thread is associated with the scheduler in effect during execution of the constructor.

Parameters:

scheduling - The SchedulingParameters associated with this (And possibly other instances of Schedulable). When scheduling is null and the creator is a schedulable, SchedulingParameters is a clone of the creator's value created in the same memory area as this. When scheduling is null and the creator is a Java thread, the contents and type of the new SchedulingParameters object is governed by the associated scheduler.

release - The ReleaseParameters associated with this (and possibly other instances of Schedulable). When release is null the new RealtimeThread will use a clone of the default ReleaseParameters for the associated scheduler created in the memory area that contains the RealtimeThread object.

memory - The MemoryParameters associated with this (and possibly other instances of Schedulable). When memory is null, the new RealtimeThread receives null value for its memory parameters, and the amount or rate of memory allocation for the new thread is unrestricted, and it may access the heap.

area - The initial memory area of this handler.

config - The ConfigurationParameters associated with this (and possibly other instances of Schedulable). When config is null, this RealtimeThread will reserve no space for preallocated exceptions and implementation-specific values will be set to their implementation-defined defaults.

dispatcher - The TimeDispatcher to use for realtime sleep and determining the period of a periodic thread.

group - The RealtimeThreadGroup of the newly created realtime thread or the parent's realtime thread group when null.

logic - The Runnable object whose run() method will serve as the logic for the new RealtimeThread. When logic is null, the run() method in the new object will serve as its logic.

Throws:

StaticIllegalArgumentException - when the parameters are not compatible with the associated scheduler, the current thread group is not a RealtimeThreadGroup and group is null, or the affinity specified is not subsumed by the affinity of its closest threads RealtimeThreadGroup instance.

IllegalAssignmentError - when the new RealtimeThread instance cannot hold a reference to any of the values of scheduling, release, memory, or group, when those parameters cannot hold a reference to the new RealtimeThread, when the new RealtimeThread instance cannot hold a reference to the values of area or logic, when the initial memory area is not specified and the new RealtimeThread instance cannot hold a reference to the default initial memory area, and when the thread may not use the heap, as specified by its memory parameters, and any of the following is true:

• the initial memory area is not specified,
• the initial memory is heap memory,
• the initial memory area, scheduling, release, memory, or group is allocated in heap memory.
• when this is in heap memory, or
• logic is in heap memory.

ScopedCycleException - when memory is a scoped memory area that has already been entered from a memory area other than the current scope.

Since:

RTSJ 2.0

Method Detail

run

public void run()

run contains only a call to logic.run if logic is not null. If this thread is to be started without providing a runnable instance, this method should be redefined to implement the thread body. If a runnable is provided, run calls the runnable's run method. Note that any redefinition of run() must call super.run() in case it is desired that the logic provided to the constructor is to be executed as well.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

addToFeasibility

public boolean addToFeasibility()

addToFeasibility notifies the scheduler associated with this that this schedulable object's scheduling, release, memory, and processing group parameters take part in the feasibility analysis.

In case this schedulable object is already part of the feasiblility analysis, do nothing.

Specified by:

addToFeasibility in interface Schedulable

Returns:

true iff the resulting system is feasible.

currentRealtimeThread

public static RealtimeThread currentRealtimeThread()
                                            throws java.lang.ClassCastException

currentRealtimeThread returns a reference to the current RealtimeThread.

This may also be called within an AsyncBaseEventHandler. The result, however, may not be the same for separate invocations of such a handler.

Returns:

A reference to the current RealtimeTread.

Throws:

java.lang.ClassCastException - iff the current thread is not an instance of RealtimeThread or an AsyncBaseEventHandler.

deschedulePeriodic

public void deschedulePeriodic()

deschedulePeriodic deschedules this thread if its release parameters are PeriodicParameters. Else, nothing will happen.

getMemoryParameters

public MemoryParameters getMemoryParameters()

getMemoryParameters returns a reference to the MemoryParameters of this RealtimeThread.

Specified by:

getMemoryParameters in interface Schedulable

Returns:

the MemoryParameters of this RealtimeThread.

getMemoryArea

public MemoryArea getMemoryArea()

getMemoryArea returns the initial memory area provided to the constructor of this thread. If none was provided, the default is the current allocation context when this was constructed.

Returns:

the initial memory area of this RealtimeThread.

Since:

RTSJ V1.0.1

getProcessingGroupParameters

public ProcessingGroupParameters getProcessingGroupParameters()

getProcessingGroupParameters returns the current ProcessingGroupParameters of this RealtimeThread.

Specified by:

getProcessingGroupParameters in interface Schedulable

Returns:

the ProcessingGroupParameters

getReleaseParameters

public ReleaseParameters getReleaseParameters()

getReleaseParameters returns the current ReleaseParameters of this RealtimeThread.

Specified by:

getReleaseParameters in interface Schedulable

Returns:

the ReleaseParameters.

getScheduler

public Scheduler getScheduler()

getScheduler returns the current scheduler of this RealtimeThread.

Specified by:

getScheduler in interface Schedulable

Returns:

the scheduler.

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()

getSchedulingParameters returns the SchedulingParameters of this RealtimeThread.

Specified by:

getSchedulingParameters in interface Schedulable

Returns:

the SchedulingParameters.

interrupt

public void interrupt()

interrupt causes a generic AsynchronouslyInterruptedException to be thrown in this RealtimeThread. The interrupted state will be set to pending. The semantics of Thread.interrupt() are preserved.

Overrides:

interrupt in class java.lang.Thread

removeFromFeasibility

public boolean removeFromFeasibility()

removeFromFeasibility informs the scheduler associated with this RealtimeThread that this RealtimeThread should no longer be taken into account in the feasibility analysis.

Specified by:

removeFromFeasibility in interface Schedulable

Returns:

true iff this could be removed successfully, false iff this was not part of the feasible set of the assigned scheduler.

schedulePeriodic

public void schedulePeriodic()

schedulePeriodic resumes the execution of a periodic thread, i.e., unblocks waitForNextPeriod. This can be used to resume execution in a deadline miss condition.

If the release parameters are not an instance of PeriodicParameters, this function has no effect.

setMemoryParameters

public RealtimeThread setMemoryParameters(MemoryParameters memory)
                                   throws java.lang.IllegalThreadStateException

setMemoryParameters replaces the memory parameters for this RealtimeThread with the parameters provided.

This change may change the feasibility of the current feasible set of this RealtimeThread's scheduler.

In JamaicaVM, this change becomes effective immediately.

Specified by:

setMemoryParameters in interface Schedulable

Parameters:

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Throws:

StaticIllegalArgumentException - if the memory parameter value is not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if memory and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException

Since:

RTSJ 2.0 returns itself

setProcessingGroupParameters

public void setProcessingGroupParameters(ProcessingGroupParameters group)

setProcessingGroupParameters sets the processing group parameters of this thread.

In JamaicaVM, this change becomes effective immediately.

This change may change the feasibility of the current feasible set of this RealtimeThread's scheduler.

Specified by:

setProcessingGroupParameters in interface Schedulable

Parameters:

group - the new processing group parameters to be applied for the next release of this. If null, the default value for the scheduler will be used.

Throws:

StaticIllegalArgumentException - if the group argument is not compatible with the scheduler of this RealtimeThread.

setReleaseParameters

public RealtimeThread setReleaseParameters(ReleaseParameters release)
                                    throws java.lang.IllegalThreadStateException

setReleaseParameters replaces the release parameters for this RealtimeThread with the parameters provided.

This change may change the feasibility of the current feasible set of this RealtimeThread's scheduler.

In JamaicaVM, this change of periodic parameters becomes effective after the execution of the next period, i.e., on the next call to waitForNextPeriod or waitForNextPeriodInterruptible.

Specified by:

setReleaseParameters in interface Schedulable

Parameters:

release - the new ReleaseParameters. If null, the default value for the associated scheduler will be used.

Throws:

StaticIllegalArgumentException - if the release parameter value is not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if release and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - if the old ReleaseParameters + * are periodic, the new ReleaseParameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

Since:

RTSJ 2.0 returns itself

setScheduler

public void setScheduler(Scheduler scheduler,
                         SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         ProcessingGroupParameters group)
                  throws StaticIllegalArgumentException,
                         IllegalAssignmentError,
                         java.lang.IllegalThreadStateException,
                         java.lang.SecurityException

setScheduler set the scheduler and scheduling, release, memory, and processing group parameters for this RealtimeThread.

The change of the scheduler and scheduling and memory parameters will take place immediately for the default scheduler. release and processing group parameters will take effect on the next release.

This change may change the feasibility of the current feasible set of this RealtimeThread's scheduler.

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler - The scheduler to be used for this RealtimeThread. Must not be null.

scheduling - SchedulingParameters to be associated with the RealtimeThread. If null, the default value of the scheduler will be used.

release - the new ReleaseParameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

group - the new processing group parameters to be applied for the next release of this. If null, use the default value for the scheduler.

Throws:

StaticIllegalArgumentException - if scheduler is null or the scheduling, release, memory, or processing group parameters are not compatible with the scheduler.

IllegalAssignmentError - if scheduler, scheduling, release, memory, or group reside in memory areas whose objects cannot be referred to by this or this object resides in a memory area that cannot be referenced by scheduling, release, or memory.

java.lang.IllegalThreadStateException - if the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

java.lang.SecurityException - if setting of the scheduler is not allowed by the current RealtimeSystem setting.

setScheduler

public RealtimeThread setScheduler(Scheduler scheduler)
                            throws StaticIllegalArgumentException,
                                   IllegalAssignmentError,
                                   java.lang.SecurityException

setScheduler sets the scheduler for this RealtimeThread. If this has been admitted to the feasible set, it remains in the feasible set.

This change may change the feasibility of the current feasible set of this RealtimeThread's scheduler.

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler - the new scheduler to be used. Must not be null.

Throws:

StaticIllegalArgumentException - iff the scheduler is null or the current parameters of this are not compatible with the new scheduler.

IllegalAssignmentError - if scheduler and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.SecurityException - if setting of the scheduler is not allowed by the current RealtimeSystem setting.

Since:

RTSJ 2.0 returns itself

setSchedulingParameters

public RealtimeThread setSchedulingParameters(SchedulingParameters scheduling)
                                       throws java.lang.IllegalThreadStateException

setSchedulingParameters sets the scheduling parameters for this RealtimeThread.

In JamaicaVM, this change of scheduling parameters becomes effective immediately for the default PriorityScheduler.

Specified by:

setSchedulingParameters in interface Schedulable

Parameters:

scheduling - the new scheduling parameters.

Throws:

StaticIllegalArgumentException - iff scheduling is not compatible with the scheduler.

IllegalAssignmentError - if scheduling and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException

Since:

RTSJ 2.0 returns itself

sleep

public static void sleep(Clock clock,
                         HighResolutionTime<?> time)
                  throws java.lang.InterruptedException

Sleep for a given relative or absolute time using the given clock. The resolution of the time slept depends on the provided clock.

If time is a relative time, then wait for this relative time.

If the time is an absolute time, wait until clock reaches this time. If the given time is already passed, return immediately.

Note: If time uses a different time-base other than clock, time is associated with clock for purposes of this method. After the method has been executed, the old clock will be re-associated with time.

Note: Although it is permissible to call sleep when control is in an AsyncBaseEventHandler, this is not recommended! The method causes the thread that executes the handler to sleep and might also block other handlers that are executed by the same thread!

Note: It only makes sense to call this method with clocks that represent a kind of a date or calendar time. If there is a different clock available (e.g. a clock corresponding to the CPU execution time of the VM) and used as an argument, an StaticIllegalArgumentException will be thrown to prevent undefined behavior.

Parameters:

clock - the clock relative which we want to sleep. If null, Clock.getRealtimeClock() will be used.

time - the AbsoluteTime or RelativeTime to sleep.

Throws:

java.lang.InterruptedException - if we are interrupted while sleeping.

StaticIllegalArgumentException - if time is a relative time less than zero or clock doesn't support the concept of date.

java.lang.UnsupportedOperationException - if clock doesn't support the concept of date.

sleep

public static void sleep(HighResolutionTime<?> time)
                  throws java.lang.InterruptedException

Sleep for a given relative or absolute time using the clock associated with time. If no clock is associated, Clock.getRealtimeClock() is used.

If time is a relative time, then wait for this relative time.

If time is an absolute time, wait until this time is reached. If the given time has already passed, return immediately.

Note: Although it is permissible to call sleep when control is in an AsyncBaseEventHandler, this is not recommended! The method causes the thread that executes the handler to sleep and might also block other handlers that are executed by the same thread!

Parameters:

time - the AbsoluteTime or RelativeTime to sleep.

Throws:

java.lang.InterruptedException - if we are interrupted while sleeping.

StaticIllegalArgumentException - if time is a relative time less than zero or if time is null.

java.lang.UnsupportedOperationException - if clock doesn't support the concept of date.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)
                      throws StaticIllegalArgumentException,
                             IllegalAssignmentError,
                             java.lang.IllegalThreadStateException

setIfFeasible performs a feasibility analysis using the provided release, memory, and processing group parameters. If the system remains feasible with these new parameters, the parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - the new release parameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

group - the new processing group parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new release, memory, and group parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if release, memory or group and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             ProcessingGroupParameters group)
                      throws StaticIllegalArgumentException,
                             IllegalAssignmentError,
                             java.lang.IllegalThreadStateException

setIfFeasible performs a feasibility analysis using the provided release and processing group parameters. If the system remains feasible with these new parameters, the parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - the new release parameters. If null, the default value for the associated scheduler will be used.

group - the new processing group parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new release, and group parameters have been activated. false iff the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if release or group and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory)
                      throws StaticIllegalArgumentException,
                             IllegalAssignmentError,
                             java.lang.IllegalThreadStateException

setIfFeasible performs a feasibility analysis using the provided release and memory parameters. If the system remains feasible with these new parameters, the parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - the new release parameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new release, and memory parameters have been activated. false iff the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if release or memory and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

setIfFeasible

public boolean setIfFeasible(SchedulingParameters sched,
                             ReleaseParameters release,
                             MemoryParameters memory)
                      throws StaticIllegalArgumentException,
                             IllegalAssignmentError,
                             java.lang.IllegalThreadStateException

setIfFeasible performs a feasibility analysis using the provided scheduling, release, and memory parameters. If the system remains + * feasible with these new parameters, the scheduling, release, and memory parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

sched - the new scheduling parameters. If null, the default value for the associated scheduler will be used. This default value may be null.

release - the new release parameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new scheduling, release, and memory parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if sched, release, or memory and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - if the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

Since:

RTSJ V1.0.1

setIfFeasible

public boolean setIfFeasible(SchedulingParameters sched,
                             ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)

setIfFeasible performs a feasibility analysis using the provided scheduling, release, memory, and processing group parameters. If the system remains feasible with these new parameters, the scheduling, release, memory, and processing group parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

sched - the new scheduling parameters. If null, the default value for the associated scheduler will be used. This default value may be null.

release - the new release parameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

group - the new processing group parameters. If null, the current default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new scheduling, release, memory, and group parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if sched, release, memory, or group and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

Since:

RTSJ V1.0.1

addIfFeasible

public boolean addIfFeasible()

addIfFeasible adds this to the feasibility analysis of the associated scheduler if the resulting system will be feasible.

If the object is already included in the feasible set, do nothing.

Specified by:

addIfFeasible in interface Schedulable

Returns:

true if this was admitted to the feasible set. false if this was not admitted or if this was already part of the feasible set.

waitForNextPeriod

public static boolean waitForNextPeriod()
                                 throws java.lang.IllegalThreadStateException

waitForNextPeriod delays the current periodic thread until the beginning of the next period. The first period starts when the thread's logic starts to run, all successive periods start after a call to waitForNextPeriod or waitForNextPeriodInterruptible returns.

If the last call to waitForNextPeriod or waitForNextPeriodInterruptible returned false and schedulePeriodic() was not called since, this will block until a call to schedulePeriodic().

Returns:

false if this thread is in a deadline miss condition. In this case, the thread is descheduled and the miss handler is fired.

Throws:

java.lang.IllegalThreadStateException - if the release parameters of this are not of type PeriodicParameters.

java.lang.ClassCastException - if the current thread is not an instance of RealtimeThread.

Since:

RTSJ V1.0.1 changed from an instance method to a static method.

waitForNextPeriodInterruptible

public static boolean waitForNextPeriodInterruptible()
                                              throws java.lang.IllegalThreadStateException,
                                                     java.lang.InterruptedException

waitForNextPeriodInterruptible is an exact copy of waitForNextPeriod, but permits to be interrupted when waiting for the next period or when waiting for a call to schedulePeriodic().

waitForNextPeriodInterruptible delays the current periodic thread until the beginning of the next period. The first period starts when the thread's logic starts to run, all successive periods start after a call to waitForNextPeriod or waitForNextPeriodInterruptible returns.

If the last call to waitForNextPeriod or waitForNextPeriodInterruptible returned false and schedulePeriodic() was not called since, this will block until a call to schedulePeriodic().

Returns:

false if this thread is in a deadline miss condition. In this case, the thread is descheduled and the miss handler is fired.

Throws:

java.lang.IllegalThreadStateException - if the release parameters of this are not of type PeriodicParameters.

java.lang.ClassCastException - if the current thread is not an instance of RealtimeThread.

java.lang.InterruptedException - if this thread is interrupted by interrupt() or AsynchronouslyInterruptedException.fire() during the call to this method.

Since:

RTSJ V1.0.1 changed from an instance method to a static method.

release

public void release()

Increase the release count of the current realtime thread. When the thread is blocked in waitForNextRelease(), cause the thread to unblock. Otherwise, change the thread state so that next call this method returns immediately.

Since:

RTSJ 2.0

waitForNextRelease

public static boolean waitForNextRelease()
                                  throws java.lang.ClassCastException,
                                         StaticIllegalStateException

Block the current realtime thread until the beginning of the next period or a call to its release() method. The first period starts when the thread's logic starts to run, all successive periods start after a call to waitForNextRelease() returns.

Returns:

either false when the thread is in a deadline miss condition or true otherwise. When a deadline miss condition occurs is defined by its thread's scheduler.

Throws:

StaticIllegalStateException - when this does not have a reference to a ReleaseParameters type of either PeriodicParameters or AperiodicParameters.

java.lang.ClassCastException - when the current thread is not an instance of RealtimeThread.

Since:

RTSJ 2.0

waitForNextReleaseInterruptible

public static boolean waitForNextReleaseInterruptible()
                                               throws java.lang.IllegalThreadStateException,
                                                      java.lang.InterruptedException,
                                                      java.lang.ClassCastException

Same as waitForNextRelease() except it can throw an interrupted exception

Returns:

either false when the thread is in a deadline miss condition or true otherwise. When a deadline miss condition occurs is defined by its thread's scheduler.

Throws:

java.lang.InterruptedException - when the thread is interrupted by interrupt() or AsynchronouslyInterruptedException.fire() during the time between calling this method and returning from it and the ReleaseParameters.isRousable() on its release parameters returns true.

An interrupt during waitForNextPeriodInterruptible() is treated as a release for purposes of scheduling. This is likely to disrupt proper operation of the periodic thread. The timing behavior of the thread is unspecified until the state is reset by altering the thread's release parameters or the thread is no longer in a deadline miss state.

StaticIllegalStateException - when this does not have a reference to a ReleaseParameters type of either PeriodicParameters or AperiodicParameters.

java.lang.ClassCastException - when the current thread is not an instance of RealtimeThread.

java.lang.IllegalThreadStateException

Since:

RTSJ 2.0

getCurrentMemoryArea

public static MemoryArea getCurrentMemoryArea()

Get the memory area that the calling Schedulable object has for its allocation context. This method may be called from a normal thread, but it should then the allocation context should be either HeapMemory or ImmortalMemory. Realtime threads use all allocation contexts.

Returns:

the current allocation context

start

public void start()

start starts this RealtimeThread. As needed, the new thread will initialize its scope stack and delay until the requested start time.

Overrides:

start in class java.lang.Thread

startPeriodic

public void startPeriodic(PhasingPolicy policy)
                   throws LateStartException,
                          IllegalTaskStateException

Starts a periodic thread with the specified phasing policy.

Parameters:

policy - The phasing policy to be applied when the start time given in the realtime thread's associated PeriodicParameters is in the past.

Throws:

LateStartException - when the actual start time is after the assigned start time and the phasing policy is PhasingPolicy.STRICT_PHASING.

IllegalTaskStateException - when the configured Scheduler and SchedulingParameters for this RealtimeThread are not compatible or the thread is does not have periodic parameters with an absolute start time.

Since:

RTSJ 2.0

setProcessingGroupParametersIfFeasible

public boolean setProcessingGroupParametersIfFeasible(ProcessingGroupParameters group)

setProcessingGroupParametersIfFeasible performs a feasibility analysis using the provided processing group parameters. If the system remains feasible with these new parameters, parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setProcessingGroupParametersIfFeasible in interface Schedulable

Parameters:

group - the new processing group parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new group parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the group parameter value is not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - If group and this reside in memory areas whose objects cannot refer to one another (in both directions).

setSchedulingParametersIfFeasible

public boolean setSchedulingParametersIfFeasible(SchedulingParameters scheduling)

setSchedulingParametersIfFeasible performs a feasibility analysis using the provided scheduling parameters. If the system remains feasible with these new parameters, the scheduling parameters are replaced.

In JamaicaVM, this change of scheduling parameters becomes effective immediately for the default PriorityScheduler.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setSchedulingParametersIfFeasible in interface Schedulable

Parameters:

scheduling - the new scheduling parameters. If null, the default value of the of the associated scheduler will be used. This default value may be null.

Returns:

true iff the resulting system is feasible and the new scheduling parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if sched, release, memory, or group and this reside in memory areas whose objects cannot refer to one another (in both directions).

setReleaseParametersIfFeasible

public boolean setReleaseParametersIfFeasible(ReleaseParameters release)
                                       throws java.lang.IllegalThreadStateException

setReleaseParametersIfFeasible performs a feasibility analysis using the provided release parameters. If the system remains feasible with the new parameters, the parameters are replaced.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setReleaseParametersIfFeasible in interface Schedulable

Parameters:

release - the new release parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new release parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if release and this reside in memory areas whose objects cannot refer to one another (in both directions).

java.lang.IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

setMemoryParametersIfFeasible

public boolean setMemoryParametersIfFeasible(MemoryParameters memory)

setMemoryParametersIfFeasible performs a feasibility analysis using the provided memory parameters. If the system remains feasible with the new memory parameters, the parameters are replaced.

In JamaicaVM, this change becomes effective immediately.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Specified by:

setMemoryParametersIfFeasible in interface Schedulable

Parameters:

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Returns:

true iff the resulting system is feasible and the new release, memory, and group parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

Throws:

StaticIllegalArgumentException - if the memory parameter value is not compatible with the scheduler associated to this RealtimeThread.

IllegalAssignmentError - if memory and this reside in memory areas whose objects cannot refer to one another (in both directions).

getMemoryAreaStackDepth

public static int getMemoryAreaStackDepth()

getMemoryAreaStackDepth returns the current size of the stack of entered memory areas of the current thread.

Returns:

the size of the memory area stack of the current thread.

getOuterMemoryArea

public static MemoryArea getOuterMemoryArea(int index)

getOuterMemoryArea returns the MemoryArea in the stack of entered memory areas at the given index. Return null if index is not a valid index in the stack (index < 0 or index >= getMemoryAreaStackDepth()).

ensure

   ((index >= 0) &&
    (index <  getMemoryAreaStackDepth()) || (Result == null),

    (index <  0) ||
    (index >= getMemoryAreaStackDepth()) || (Result != null))

 

Parameters:

index - the index into the stack

Returns:

the memory area at that index or null if index is not valid.

getInitialMemoryAreaIndex

public static int getInitialMemoryAreaIndex()

getInitialMemoryAreaIndex returns the index of the current RealtimeThread's or AsyncBaseEventHandler's initial memory area.

ensure

   (getOuterMemoryArea(Result) == currentRealtimeThread().getMemoryArea().
 

 

Returns:

the index of the initial memory area of the current RealtimeThread.

Throws:

java.lang.ClassCastException - iff the current thread is not an instance of RealtimeThread or an AsyncBaseEventHandler.

StaticIllegalStateException - when the memory area stack of the current Schedulable has changed from its initial configuration and the memory area at the originally specified initial memory area index is not the initial memory area, thus the index is invalid.

getDispatcher

public TimeDispatcher getDispatcher()

Gets the dispatcher associated with this Timable.

Specified by:

getDispatcher in interface Releasable<Timable,TimeDispatcher>

Specified by:

getDispatcher in interface Timable

Returns:

that dispatcher.

Throws:

java.lang.UnsupportedOperationException - always, since it is not yet implemented.

fire

public void fire()

Called by the dispatcher associated with this to indicate that a time event has occured.

Specified by:

fire in interface AsyncTimable

Throws:

java.lang.UnsupportedOperationException - always, since it is not yet implemented.