Requirements and Conventions

The base requirements of this specification are:

Except as specifically required by this specification, any implementation shall fully conform to a Java platform configuration.
Except as noted in this chapter, any implementation of this specification shall implement all classes and methods in this specification. In particular, every implementation must include a conformant implementation of the PriorityScheduler class.
The javax.realtime package shall contain no public or protected methods not included in this specification.
The JVM shall not be implemented in a way that permits unbounded priority inversion in any scheduling interaction it implements.
Subject to the usual assumptions, the methods in javax.realtime can safely be used concurrently by multiple threads unless it is otherwise documented.
No specific instance of PhysicalMemoryTypeFilter is required, but every implementation must support at least one such instance with the characteristic that it supports access to the range of physical memory that can be made accessible to the implementation.
Static final values, as found in AperiodicParameters, PhysicalMemoryManager, SporadicParameters, RealtimeSystem, and PriorityScheduler, must be handled by the implementation such that their values cannot be resolved at compile time.

Many aspects of this specification set a minimum requirement, but permit the implementation latitude in its implementation. For instance, the required priority scheduler requires at least 28 consecutively numbered real-time priorities. It does not, however, specify the numeric value of the maximum and minimum priorities. Implementations are encouraged to offer as many real-time priority levels as they can support.

Except where otherwise specified, when this specification requires object creation the object is created in the current allocation context.

Optional Facilities

There are no bounds on extensions based on this specification, except that only extensions that conform with future versions of this specification may be implemented in the javax.realtime package.

Several optional extensions are included in this specification. An application cannot depend on these facilities in every implementation, but if an optional facility is implemented, the application may rely on it to behave as specified here. Those extensions are:

Cost enforcement	Allows the application to control the processor utilization of a schedulable object.
Processing Group enforcement	Allows the application to control the processor utilization of a group of schedulable objects
Processing Group deadline less than period	Allows the application to specify a processing group deadline less than the processing group period
Priority Ceiling Emulation Protocol	An alternative to priority inheritance for priority inversion avoidance
Atomic access to raw memory	Most atomic access is optional. The implementation may provide the raw memory access characteristics in system properties of the form `javax.realtime.atomicaccess_<xxx>`.
Allocation-rate enforcement on heap allocation	Allows the application to limit the rate at which a schedulable object creates objects in the heap.

The ProcessingGroupParameters class is only functional on systems that support the processing group enforcement option. Cost enforcement, and cost overruns handlers are only functional on systems that support the cost enforcement option. If processing group enforcement is supported, ProcessingGroupParameters must function as specified. If cost enforcement is supported, cost enforcement, and cost overrun handlers must function as specified.

If the processing group deadline less than period is not supported, values passed to the constructor for ProcessingGroupParameters and its setDeadline method are constrained to be equal to the period. If the option is supported, processing group deadlines less than the period must be supported and function as specified.

If priority ceiling emulation is supported, PriorityCeilingEmulation must be implemented as specified. If priority ceiling emulation is not supported, PriorityCeilingEmulation must be present, but the implementation may not permit its use as a monitor control policy.

If heap allocation rate enforcement is supported, it must be implemented as specified. If heap allocation rate enforcement is not supported, the allocation rate attribute of MemoryParameters must be checked for validity but otherwise ignored by the implementation.

The following semantics are optional for an RTSJ implementation designed and licensed exclusively as a development tool:

The priority scheduler need not support fixed-priority preemptive scheduling or priority inheritance. This does not excuse an implementation from fully supporting the relevant APIs. It only reduces the required behavior of the underlying scheduler to the level of the scheduler in the Java specification extended to at least 28 priorities.
No semantics constraining timing beyond the requirements of the Java specifications need be supported. Specifically, garbage collection may delay any thread without bound and any delay in delivering asynchronously interrupted exceptions is permissible including never delivering the exception. Note, however, that if any AIE other than the generic AIE is delivered, it must meet the AIE semantics, and all heap-memory-related semantics other than preemption remain fully in effect. Further, relaxed timing does not imply relaxed sequencing. For instance, semantics for scoped memory must be fully implemented.
The RTSJ semantics that alter standard Java method behavior—such as the modified semantics for Thread.setPriority and Thread.interrupt—are not required for a development tool, but such deviations from the RTSJ must be documented, and the implementation must be able to generate a run-time warning each time one of these methods deviates from standard RTSJ behavior.
These relaxed requirements set a floor for RTSJ development system tool implementations. A development tool may choose to implement semantics that are not required.

Conditionally-Required Facilities

An implementation must support conditionally-required facilities if the underlying hardware and software permits. This specification includes three conditionally-required facilities:

`POSIXSignalHandler`	This class shall be implemented on every platform where POSIX signals are supported
`RawMemoryFloatAccess`	This shall be implemented on every platform for which the base JVM includes support for the float and double types.
Mapping memory	If the system supports address translation, the implementation shall support the memory mapping features of the raw memory access classes.

If POSIX signals are not supported, the POSIXSignalHandler class must not be present. If POSIX signals are supported, POSIXSignalHandler must be implemented as specified.

If floating point is not supported by the platform, RawMemoryFloatAccess must not be present. If floating point is supported, then RawMemoryFloatAccess must be implemented as specified.

Required Documentation

Each implementation of the RTSJ is required to provide documentation for several behaviors:

If the feasibility testing algorithm is not the default, document the feasibility testing algorithm.
If schedulers other than the base priority scheduler are available to applications, document the behavior of the scheduler and its interaction with each other scheduler as detailed in the Scheduling chapter. Document the list of classes that constitute schedulable objects for the scheduler unless that list is the same as the list of schedulable objects for the base scheduler. If there are restrictions on use of the scheduler from a non-heap context, document those restrictions.
A schedulable object that is preempted by a higher-priority schedulable object is placed in the queue for its active priority, at a position determined by the implementation. If the preempted schedulable object is not placed at the front of the appropriate queue the implementation must document the algorithm used for such placement. Placement at the front of the queue may be required in a future version of this specification.
If the implementation supports cost enforcement, then the implementation is required to document the granularity at which the current CPU consumption is updated.
The memory mapping implemented by any physical memory type filter must be documented unless it is a simple sequential mapping of contiguous bytes.
The implementation must fully document the behavior of any subclasses of GarbageCollector.
An implementation that provides any MonitorControl subclasses not detailed in this specification must document their effects, particularly with respect to priority inversion control and which (if any) schedulers fail to support the new policy.
If on losing "boosted" priority due to a priority inversion avoidance algorithm, the schedulable object is not placed at the front of its new queue, the implementation must document the queuing behavior.
For any available scheduler other than the base scheduler an implementation must document how, if at all, the semantics of synchronization differ from the rules defined for the default PriorityInheritance monitor control policy. It must supply documentation for the behavior of the new scheduler with priority inheritance (and, if it is supported, priority ceiling emulation protocol) equivalent to the semantics for the base priority scheduler found in the Synchronization chapter. If there are restrictions on use of the scheduler from a no-heap context, the documentation must detail the effect of these restrictions for each RTSJ API.
The worst-case response interval between firing an AsyncEvent because of a bound happening to releasing an associated AsyncEventHandler (assuming no higher-priority schedulable objects are runnable) must be documented for some reference architecture.
The interval between firing an AsynchronouslyInterruptedException at an ATC-enabled thread and first delivery of that exception (assuming no higher-priority schedulable objects are runnable) must be documented for some reference architecture.
If cost enforcement is supported, and the implementation assigns the cost of running finalizers for objects in scoped memory to any schedulable object other than the one that caused the scope's reference count to drop to zero by leaving the scope, the rules for assigning the cost shall be documented.
If cost enforcement is supported, and enforcement (blocked-by-cost-overrun) can be delayed beyond the enforcement time granularity, the maximum such delay shall be documented.
If the implementation of RealtimeSecurity is more restrictive than the required implementation, or has run-time configuration options, those features shall be documented.
For each supported clock, the documentation must specify whether the resolution is settable, and if it is settable the documentation must indicate the supported values.
If an implementation includes any clocks other than the required real-time clock, their documentation must indicate in what contexts those clocks can be used. If they cannot be used in no-heap context, the documentation must detail the consequences of passing the clock, or a time that uses the clock to a no-heap schedulable object.

Conventions

Throughout the RTSJ, when we use the word code, we mean code written in the Java programming language. When we mention the Java language in the RTSJ, that also refers to the Java programming language. The use of the term heap in the RTSJ will refer to the heap used by the runtime of the Java language.

Definitions

A thread is an instance of the java.lang.Thread class.

A real-time thread is an instance of the javax.realtime.RealtimeThread class.

A Java thread is a thread that is not a real-time thread.

A no-heap real-time thread is an instance of the javax.realtime.NoHeapRealtimeThread class.

An asynchronous event handler is an instance of the javax.realtime.AsyncEventHandler class.

The term Schedulable object is distinct from the term schedulable object (SO). Every object that implements the Schedulable interface can be termed a Schedulable object, but only objects that are recognized as dispatchable entities by the base scheduler are schedulable objects with respect to that scheduler. The base scheduler's set of schedulable objects comprises instances of RealtimeThread and AsyncEventHandler. Other schedulers may support a different set of schedulable objects, but this specification only defines the behavior of the base scheduler so the term schedulable object should be understood as "schedulable by the base scheduler."