The OVM implementation of the Realtime Specification for Java (RTSJ).

## Implementation Status and Notes

THIS DOCUMENT IS QUITE OUT OF DATE. WE ARE IN THE PROCESS OF BRINGING EVERYTHING THAT HAS BEEN IMPLEMENTED UP TO THE RTSJ 1.0.1 LEVEL.

Each class contains implementation notes when needed, discussing problems and limitations, either with the API as defined in the RTSJ, or with the implementation strategy that has been chosen. Some of the major issues are discussed below.

The state of each class within the RTSJ is also described below.

### General Issues

#### Threads

The basic realtime threading support is in place and we support periodic threads and basic deadline monitoring of periodic threads. There is deadline monitoring for non-periodic threads too.

The deadlines for async event handlers are not currently tracked correctly. Whenever `getAndDecrementPendingFireCount` is called we should reset the deadline relative to the next event firing. Problem is we don't know when that event actually fired.

We don't have any of the memory scope stack maintenance code in place, though this could be done without actually implementing memory areas.

We don't know how to deal with dynamic modification of parameter objects and/or their internal values in many cases. There are atomicity issues with the `setIfFeasible` methods because, for example, with setting scheduling parameters the thread may be in a legal state for a change when we swap in the new parameters, but if the feasibility tests fails, the thread may have changed state when we try to swap back the old parameters.

We support priority changes when a thread is blocked acquiring a monitor. This is an extension to the spec that we expect to be in 1.0.1. Actually we support priority changes at any time - which will also be in 1.0.1

Our intepretation of the behaviour of {@link javax.realtime.RealtimeThread#waitForNextPeriod} is different to that of the RI. This will be fixed as the entire behaviour of wfnp in 1.0.1 has been restated in much clearer terms to ensure correct (or at least consistent) interaction between periodic threads, deadline monitoring and cost monitoring.

A {@link javax.realtime.NoHeapRealtimeThread} behaves exactly the same as a {@link javax.realtime.RealtimeThread}. Without memory areas the heap must be used.

Priority Inversion Avoidance and Monitor Control Policies

We support a full implementation of the Priority Inheritance Protocol that deals with threads having their priorities changed at any time and which can sleep, yield etc.

We do not support the Priority Ceiling Emulation Protocol and consequently there is no support for setting the monitor control policy of objects.

#### Synchronization of Parameter Classes

The RTSJ states that all parameter objects are not thread-safe and the caller is responsible for synchronization. But the runtime doesn't know how the application will perform synchronization, nor does the application know how the runtime performs synchronization. This effectively means correct synchronization is impossible - these classes should be immutable. Within the runtime methods that use public mutating methods of parameter objects must synchronize on that object. We suggest that applications do the same thing. The package-private register/unregister methods take care of their own synchronization.

#### Null values and Default values

There are many problems, particularly with the methods of {@link javax.realtime.Schedulable} with regard to whether `null` values are permitted, what default values should be if unspecified and the treatment of null parameters in general. A `null` parameter may mean:

- Set the value to `null`
- Use the default value
- Leave the value unchanged
- Throw IllegalArgumentException

This is a real mess that will hopefully be fixed in the 1.0.1 version of the spec.

#### Scheduler and Feasibility Tests

There are problems in the spec with regard to the default scheduler and setting default parameters for schedulables depending on what their scheduler is. The spec even allows for a schedulable, including a thread, to not be associated with a scheduler, and that is completely unworkable. The spec allows for multiple schedulers but doesn't allow for their interaction and often doesn't take into account their existence. In short bit of a mess. We circumvent this mess by assuming and enforcing that there is only one scheduler: the {@link javax.realtime.PriorityScheduler}.

There is no feasibility test supported.

The mechanism used by the `setIfFeasible` methods on {@link javax.realtime.Schedulable Schedulables} is completely broken - as it is for the RI. These methods work by changing the parameter, checking feasibility and then changing back if the feasibility test fails. However, changing parameter objects has side-effects in many cases to transmit through to the runtime the fact that key scheduling/release information may have changed. Consequently a change X=>Y=>X does not leave you in the same state as which you started and so the way these methods are implemented must be changed.

#### Async Events

The basic event mechanism is in place, similar in structure to that of the RI. Even though async event handlers should be more lightweight than threads, they actually get executed in a new thread each time the event fires. It is simply too difficult to get one thread to adapt to the different scheduling, release, group, memory parameters etc that each handler may have.

BoundAsyncEventHandlers are defined but the semantics of changing the handler parameters are not correct with respect to the current spec which requires they take effect on the next release. The updated spec will not require this.

The threads for BoundAEH are defined as daemon's so they don't keep the VM alive - as nothing tells them when to terminate (though finalization could). The RTSJ 1.0.1 update extends the VM lifecycle model to deal with events keeping the VM alive but we don't deal with that yet.

There is no support for events with sporadic release parameters. (Note that it is the handler that gets the parameters but it is really the event that is sporadic). Events are not queued and arrival times not stored and we do not check for MIT violations.

The deadlines for async event handlers are not currently tracked correctly. Whenever `getAndDecrementPendingFireCount` is called we should reset the deadline relative to the next event firing. Problem is we don't know when that event actually fired.

There is no support for external happenings and POSIX events.

One part of the spec states that an async event handler with null scheduling or release parameters should be run in the context of the thread that invokes fire() - and that is what we do. The spec does not say what happens if the event is bound to an external happening. These semantics also make it unclear what setXXXXIfFeasible means if the parameter is null. Indications are that this was an idea that got overlooked and the part of the spec that mentions this will be changed - but that requires the spec to define how nulls should be handled.

#### Asynchronous Transfer of Control

This is not supported.

#### Memory Areas

There is presently no support for memory areas other than some skeleton classes to allow compilation where {@link javax.realtime.MemoryArea} types are passed as parameters, or returned from methods.

At present very little attention has been given to how and where the RTSJ classes perform allocation. Once memory areas are active we may find that we need to control how allocation is performed (such as using immortal memory) within the RTSJ classes.

#### Clocks and Times

The API for times is quite a mess, the subclass relationships are inappropriate and in most cases methods declare that they take the generic {@link javax.realtime.HighResolutionTime} rather than one of its subclasses. It is impossible to deal with externally defined subclasses of HighResolutionTime and in many cases there is little choice but to perform conditional actions based on `instanceof` tests.

Although {@link javax.realtime.RationalTime} is defined it is not recognised by any other API, but will be treated (incorrectly) as a {@link javax.realtime.RelativeTime} value. It is far from clear what the implementations responsibilities are with regard to rational time, even for periods specified as a rational time.

The use of {@link javax.realtime.Clock Clocks} other than the real-time clock is a mystery. Although the spec allows for them it is impossible to see how they could ever be used. Consequently we do not support anything except the real-time clock.

### Class Status

The following classes are defined and mostly functional (they can be used but sometimes with restrictions - note that many exceptions will never be thrown at present, but the exception classes exist):

- AbsoluteTime
- AperiodicParameters
- AsyncEvent
- AsyncEventHandler
- BoundAsyncEventHandler
- Clock
- HighResolutionTime
- ImportanceParameters
- MemoryAccessError
- OneShotTimer
- PeriodicParameters
- PeriodicTimer

  Complete other than the lack of support for rational times. We have augmented the spec where it was lacking - eg. what to return from getFireTime if the timer hasn't been started.

- POSIXSignalHandler
- PriorityParameters
- PriorityScheduler
- RealtimeThread
- RelativeTime
- ReleaseParameters
- ResourceLimitError
- Schedulable
- Scheduler
- SchedulingParameters
- Timer

  The specification of `Timer` is very poor in the RTSJ. See the additional documentation for {@link javax.realtime.OneShotTimer} and {@link javax.realtime.PeriodicTimer} for more details on their behaviour.

- DuplicateFilterException
- IllegalAssignmentError
- InaccessibleAreaException
- MemoryInUseException
- MemoryScopeException
- MemoryTypeConflictException
- MITViolationException
- OffsetOutOfBoundsException
- ScopedCycleException
- SizeEstimator
- SizeOutOfBoundsException
- ThrowBoundaryError
- UnknownHappeningException
- UnsupportedPhysicalMemoryException

The following classes are defined but not functional (they can be used but may not behave as expected):

- MemoryParameters

  This class is complete but the runtime does not support control of allocation amounts or rates. It is far from clear exactly how the runtime should interpret the values specified in this class.

- NoHeapRealtimeThread

  Only heap memory is supported at present so a NHRTT behaves just like a RT.

- PriorityCeilingEmulation

  This class is complete (its trivial) but the API that uses it is not implemented.

- PriorityInheritance

  This class is complete (its trivial) but the API that uses it is not implemented.

- ProcessingGroupParameters

  This class is complete but none of the other API's deal with it explicitly, so it should not be used.

- RationalTime

  This class is complete but none of the other API's deal with it explicitly, so it should not be used. NOTE: this class has been deprecated in the 1.0.1 release.

- SporadicParameters

  There is currently no support for sporadic async events.

The following classes exist as skeleton definitions to allow other classes to compile (they should not be used):

- AsynchronouslyInterruptedException
- HeapMemory
- ImmortalMemory
- MemoryArea
- MonitorControl
- ScopedMemory

The following classes do not exist at all:

- GarbageCollector
- ImmortalPhysicalMemory
- Interruptible
- LTMemory
- LTPhysicalMemory
- PhysicalMemoryManager
- PhysicalMemoryTypeFilter
- RawMemoryAccess
- RawMemoryFloatAccess
- RealtimeSecurity
- RealtimeSystem
- Timed
- VTMemory
- VTPhysicalMemory
- WaitFreeDequeue
- WaitFreeReadQueue
- WaitFreeWriteQueue