 
Use of JCP site is subject to the
JCP Terms of Use and the
Oracle Privacy Policy
 |
|
Proposed Changes for RTSJ 1.0.2
|
| Change 1: |
New base requirement: 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. |
| Change 2: | New base requirement:
Except where otherwise specified, when this specification requires object creation the object is created in the current allocation context. |
| Change 3: | In required documentation (2), change "Also document" to "Document" |
| Change_4: |
In required documentation (2), add "If there are restrictions on use of the scheduler from a non-heap context, document those restrictions." |
| Change 5 | In required documentation (4), change "support" to "supports" |
| Change 6 | In required documentation (9), change "instance" to "monitor control policy" |
| Change 7 | Add at end: "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." |
| Change 8 |
Insert documentation requirement "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." |
| Change 9 |
Delete documentation requirement "An implementation may run finalizers for objects in scoped memory before the scope is reentered and before it returns from any call to getReferenceCount() for that scope. It must, however, document when it runs those finalizers." |
| Change 10 |
At end of the last documentation requirement add: "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." |
Insert new Section
System properties and their String values allocated during system initialization shall be allocated in immortal memory."
Fourth constructor, in description of @throws IllegalAssignmentError, add
"Also thrown if the new RealtimeThread instance cannot hold a reference to non-null values of area or logic."
getInitialMemoryAreaIndex() method description changed from
This method returns the position in the memory area stack of the initial memory area. Memory area stacks may include inherited stacks from parent threads. The initial memory area for the current RealtimeThread or AsyncEventHandler is the memory area given as a parameter to the constructor. The index on the memory area stack of the initial memory area is a fixed property of the real-time thread.
Returns: The index into the memory area stack of the initial memory area of the current RealtimeThread
Throws:
java.lang.ClassCastException - Thrown if the current execution context is that of a Java thread.
java.lang.IllegalStateException - Thrown if the initial memory area is not currently on the current real-time thread’s scope stack. This can happen if the thread uses executeInArea to “slide down” the stack past the initial memory area.
to
Returns the position in the initial memory area stack, of the initial memory area for the current real-time thread. Memory area stacks may include inherited stacks from parent threads. The initial memory area of a RealtimeThread or AsyncEventHandler is the memory area given as a parameter to its constructor. The index in the initial memory area stack of the initial memory area is a fixed property of the real-time thread.
If the current memory area stack of the current real-time thread is not the original stack and the memory area at the initial memory area index is not the initial memory area, then IllegalStateException is thrown.
Returns: The index into the initial memory area stack of the initial memory area of the current RealtimeThread.
Throws:
java.lang.IllegalStateException - Thrown if the memory area at the initial memory area index, in the current scope stack is not the initial memory area.
java.lang.ClassCastException - Thrown if the current execution context is that of a Java thread.
Second constructor change
IllegalAssignmentError - Thrown if the new NoHeapRealtimeThread instance cannot hold a reference to non-null values of scheduling and release, or if those parameters cannot hold a reference to the new NoHeapRealtimeThread.
to
IllegalAssignmentError - Thrown if the new NoHeapRealtimeThread instance cannot hold a reference to non-null values of scheduling, release and area, or if scheduling and release cannot hold a reference to the new NoHeapRealtimeThread.
Fourth constructor, at the end of the IllegalAssignmentError clause add
"Also thrown if area or logic cannot be stored in the new RealtimeThread object"
Change the description of active priority from
The active priority of a schedulable object, or a Java thread, is the maximum of its base priority and any priority it has acquired due to the action of priority inversion avoidance algorithms (see the Synchronization Chapter).
to
When it is not in the enforced state, the active priority of a schedulable object or a Java thread is the maximum of its base priority and any priority it has acquired due to the action of priority inversion avoidance algorithms (see the Synchronization Chapter),
In the cost monitoring semantics, at the end of bullets 4.a and 4.b, add
There may be a bounded delay between the time at which the blocking condition is removed and the time at which the SO becomes blocked-by-cost-overrun.
In Aperiodic and Sporadic Release Control for Asynchronous Event Handlers
Replace semantic 4, a-c
a. Each invocation of handleAsyncEvent, in this way, is a release.
b. The return from handleAsyncEvent is the completion of a release: the fire- Count is decremented and the front entry (if still present) removed from the
arrival-time queue.
c. Processing of any exceptions thrown by handleAsyncEvent occurs prior to completion.
with
a. Before invoking handleAsyncEvent, the fireCount is decremented and the front entry (if still present) removed from the arrival-time queue.
b. Each invocation of handleAsyncEvent, in this way, is a release.
c. The return from handleAsyncEvent is the completion of a release.
d. Processing of any exceptions thrown by handleAsyncEvent occurs prior to completion.
In Aperiodic and Sporadic Release Control for Asynchronous Event Handlers
Delete "invoked by handleAsyncEvent" from semantic 6"
Replace Aperiodic and Sporadic Release Control for Asynchronous Event Handlers
Semantics 6.a
a. The getAndDecrementPendingFireCount method decreases the fireCount by one (if it was greater than zero), and returns the old value. This removes the front entry from the arrival-time queue but does not constitute a completion: the deadline of the most current release is unchanged and the current CPU consumption is not set to zero.
with
a. The getAndDecrementPendingFireCount method decreases the fireCount by one (if it was greater than zero), and returns the old value. This removes the front entry from the arrival-time queue but otherwise has no effect on the scheduling of the current scheulable object, nor the handler itself.
Replace Aperiodic and Sporadic Release Control for Asynchronous Event Handlers
Semantics 6.c
c. The getAndIncrementPendingFireCount method attempts to increase the fireCount by one, and returns the old value. It effectively generates an arrival for this handler, and if that arrival is accepted, it becomes a release event that is added to the arrival-time queue and the fireCount is incremented by one. If the handler is not active, that is execution is not within the flow of control of handleAsyncEvent, at the time this method is called, then the handler may not be released in response to this new release event, until an additional release event is generated by firing the associated asynchronous event.
with
c. The getAndIncrementPendingFireCount method attempts to increase the fireCount by one , and returns the old value. It behaves effectively as if a private event, associated only with this handler, were fired, in accordance with semantic (1) above. This pseudo-firing is treated as a normal firing with respect to the other semantics in this section.
Add
The enforced priority of a schedulable object is a priority with no execution eligibility.
Replace processing group semantic 7a-b
a. If the state of the SO is either executing or eligible-for-execution, then the SO is placed into the state blocked-by-group-cost-overrun.
b. Otherwise, the SO must have been blocked for a reason other than blockedby-group-cost-overrun. In this case, the state change to blocked-by-groupcost-overrun is left pending: if the blocking condition for the SO is removed, then its state changes to blocked-by-group-cost-overrun.
with
a. The SO is placed into the enforced state.
b. When a SO is in the enforced state the base scheduler schedules that SO effectively as if the enforced priority were used in place of the SO’s base priority.
Replace processing group semantic 8.b.
b. Otherwise the processing group is in the enforced state. It is removed from the enforced state, the current CPU consumption of the group is set to zero, and for each member of the processing group:
i. If there is a pending state change to blocked-by-group-cost-overrun then: the pending state change is removed, and the SO remains in its current blocked state;
ii. If the SO is in the block-by-group-cost-overrun state, it is made eligible for execution.
iii. Otherwise no cost monitoring action is taken for that SO.
with
b. Otherwise the processing group is in the enforced state. It is removed from the enforced state, the current CPU consumption of the group is set to zero, and each member of the group is removed from the enforced state.
At the end of Scheduling Rationale, add
Cost enforcement may be deferred while the overrun schedulable object holds locks that are out of application control, such as locks used to protect garbage collection. Applications should include the resulting jitter in any analysis that depends on cost enforcement.
When a schedulable object is enforced because of cost overrun in a processing group the enforced priority is used for scheduling instead of the schedulable object’s base priority. The enforced priority’s application is limited. The enforced priority is not returned as the schedulable object’s priority from methods such as getPriority(),and the semantics of the active priority continue to operate when a schedulable object is enforced.
Change the description for getPolicyName() from
Gets a string representing the policy of this. The string value need not be interned, but it must be created in a memory area that is compatible with the caller’s execution environment.
to
Gets a string representing the policy of this. The string value need not be interned, but it must be created in a memory area that does not cause an illegal assignment error if stored in the current allocation context and does not cause a MemoryAccessError when accessed.
Change the description for static int getMaxPriority(java.lang.Thread thread) method from
Gets the maximum priority for the given thread. If the given thread is a real-time thread that is scheduled by an instance of PriorityScheduler, then the maximum priority for that scheduler is returned. If the given thread is a Java thread then Thread.MAX_PRIORITY is returned. Otherwise an exception is thrown.
to
Gets the maximum priority for the given thread. If the given thread is a real-time thread that is scheduled by an instance of PriorityScheduler, then the maximum priority for that scheduler is returned. If the given thread is a Java thread then the maximum priority of its thread group is returned. Otherwise an exception is thrown.
In the setPeriod() method, add "Also thrown if period is incompatible with the scheduler for any associated schedulable object." to the end of the IllegalArgumentException clause.
In the setArrivalTimeQueueOverflowBehavior() method, add the following paragraph:
Values of behavior are compared using reference equality (==) not value equality (equals()).
In the setMitViolationBehavior() method, add the following paragraph:
Values of behavior are compared using reference equality (==) not value equality (equals()).
Replace semantic 18
18. When the reference count for an instance of the class ScopedMemory is ready to be decremented from one to zero, all unfinalized objects within that area are considered ready for finalization. If after the finalizers for all unfinalized objects in the scoped memory area run to completion, the reference count for the memory area is still ready to be decremented to zero, then it is decremented to zero and the memory scope is emptied of all objects. The RTSJ implementation must complete finalization of objects in the scope and, if the reference count is zero after finalizers run, deletion of the objects in the scope before that memory scope can again become the current allocation context for any schedulable object. (This is a special case of the finalization implementation specified in The Java Language Specification, second edition, section 12.6.1)
with
18. When the reference count for an instance of the class ScopedMemory is ready to be decremented from one to zero, all unfinalized objects within that area are considered ready for finalization. If after the finalizers for all such unfinalized objects in the scoped memory area run to completion, the reference count for the memoryarea is still ready to be decremented to zero, any newly created unfinalized objects are considered ready for finalization and the process is repeated until no new objects are created or the scoped memory’s reference count is no longer ready to be decremented from one to zero. When the scope contains no unfinalized objects and its reference count is ready to be decremented from one to zero, then the reference count is decremented to zero and the memory scope is emptied of all objects. The RTSJ implementation must complete finalization of objects in the scope and, if the reference count is zero after finalizers run, deletion of the objects in the scope before that memory scope can again become the current allocation context for any schedulable object. (This is a special case of the finalization implementation specified in The Java Language Specification, second edition, section 12.6.1)
Replace semantic 19
19. Finalization of objects in scoped memory shall take place in a schedulable entity that can reference each object with assignment and reference rules no more restrictive than those in place when the object was created. Finalization may start when the all unfinalized objects in the scope are ready for finalization. The current allocation context for the finalizers is equal to the finalizing scope with a scope stack that is valid under the single parent rule. The scope stack need not be minimal; it may contain heap and immortal memory areas. The finalizing schedulable entity may be heap, or no-heap, and it may run at any real-time priority, but it is subject to boosting to avoid priority inversion,
with
19. Finalization may start when all unfinalized objects in the scope are ready for finalization. Finalizers are executed with the current allocation context set to thefinalizing scope and are executed by the schedulable object in control of the scope when its reference count is ready to be decremented from one to zero
At the end of memory management rationale, add
"If a scoped memory area is used by both heap and non-heap SOs, there could becases where a finalizer executed in non-heap context could attempt to use a heapreference left by a heap-using SO. The code in the finalizer would throw a memoryaccess error. If that exception is not caught in the finalizer, it will be handled by the implementation so finalization will continue undisturbed, but the problem in finalizer that caused the illegal memory access could be hard to locate. So, catch clauses in finalizers for objects allocated in scoped memory are even more useful than they are for normal finalizers."
In each constructor that accepts a SizeEstimator argument, add to the IllegalArgumentException clause, "or size.getEstimate() is negative"
In the enter() method insert "if the caller is a schedulable object and" in the IllegalArgumentException clause
To the enter() method, add
MemoryAccessError - Thrown if caller is a no-heap schedulable object and this memory area’s logic value is allocated in heap memory.
In the enter(logic) method, change the first two exception descriptions from
java.lang.IllegalArgumentException - Thrown if logic is null.
java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.
to
java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.
java.lang.IllegalArgumentException - Thrown if the caller is a schedulable object and logic is null.
In class description, second paragraph, replace "several parts" with "several parts (if for instance the object and its monitor are separate)"
In method reserve(Class c, int number) add throws clause
java.lang.IllegalArgumentException - Thrown if c is null.
In reserve(SizeEstimator size) add throws clause
java.lang.IllegalArgumentException - Thrown if size is null.
In reserve(SizeEstimator estimator, int number) add throws clause
java.lang.IllegalArgumentException - Thrown if estimator is null.
In each constructor that accepts a SizeEstimator argument, add to the IllegalArgumentException clause, "or size.getEstimate() is negative"
In each enter() or joinAndEnter() method, remove the IllegalThreadStateException clause it is present, and add
java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread, or if this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the SO that triggered finalization. This would include the scope containing the SO, and the scope (if any) containing the scope containing the SO.
For enter(), and enter(logic) insert "if the caller is a schedulable object and" in the IllegalArgumentException clause
For enter() add
MemoryAccessError - Thrown if caller is a no-heap schedulable object and this memory area’s logic value is allocated in heap memory.
For executeInArea(logic), add
java.lang.IllegalArgumentException - Thrown if the caller is a schedulable object and logic is null.
In the getPortal() method, delete the MemoryAccessError clause
In the getPortal() method, change "context" to "context or not on the caller's scope stack" in the IllegalAssignmentError clause.
In getReferenceCount() change the description from
Returns the reference count of this ScopedMemory. The reference count is an indication of the number of schedulable objects that may have access to this scope.
to
Returns the reference count of this ScopedMemory.
Note: A reference count of 0 reliably means that the scope is not referenced, but other reference counts are subject to artifacts of lazy/eager maintenance by the implementation.
In the join(), and join(time), methods, add
java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.
In the join(time), joinAndEnter(), joinAndEnter(time), joinAndEnter(logic), and joinAndEnter(logic, time) methods' IllegalArgumentException clause, replace "if" with "if the caller is a schedulable object and"
In the joinAndEnter(), and joinAndEnter(time) methods, add
MemoryAccessError Thrown if caller is a non-heap schedulable object and this memory area’s logic value is allocated in heap memory.
In the joinAndEnter(time), and joinAndEnter(logic, time) methods' ScopedCycleException description, change "if" to "if the caller is a schedulable object and"
In the setPortal method description, delete
IllegalThreadStateException is thrown when called by a Java thread even when the invocation could also throw IllegalArgumentException.
and change the exception descriptions from
IllegalAssignmentError - Thrown if object is not allocated in this scoped memory instance.
InaccessibleAreaException - Thrown if this memory area is not in the caller’s scope stack.
java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.
to
java.lang.IllegalThreadStateException - Thrown if the caller is a Java Thread, and object is not null.
IllegalAssignmentError - Thrown if the caller is a schedulable object, and object is not allocated in this scoped memory instance and not null.
InaccessibleAreaException - Thrown if the caller is a schedulable object, this memory area is not in the caller’s scope stack and object is not null.
Throughout the constructor and method documentation, convert references to SizeEstimator values size, and initial to size.getEstimate() and initial.getEstimate() as appropriate.
In the 7th and 8th constructors' IllegalArgument descriptions, replace "the size estimate from maximum" with "maximum.getEstimate()"
Throughout the constructor and method documentation, convert references to SizeEstimator values size, and initial to size.getEstimate() and initial.getEstimate() as appropriate.
In the 7th and 8th constructors' IllegalArgument descriptions, replace "the size estimate from maximum" with "maximum.getEstimate()"
For each method that has a Object name parameter, add the note:
Values of name are compared using reference equality (==) not value equality (equals()).
After the first paragraph of the class description, add
"No provision is made for sharing object in [memory class] with entities outside the JVM that creates them, and, while the memory backing an instance of [memory class] could be shared by multiple JVMs, the class does not support such sharing."
In the type parameter description for each constructor that has an Object type parameter, add
"Note that type values are compared by reference (==), not by value (equals)."
In the InvalidArgumentException clause of each constructor that has a SizeEstimator size parameter, add
"or size.getEstimate() is negative"
In the type parameter description for each constructor that has an Object type parameter, add
"Note that type values are compared by reference (==), not by value (equals)."
In the map(long base) method's IllegalArgumentException description, add, "or the memory-mapping hardware cannot place the physical memory at the designated address."
In the map(long base, long size) method's IllegalArgumentException description, replace
java.lang.IllegalArgumentException - Thrown if size is not greater than zero, or base is not a legal value for a virtual address.
with
java.lang.IllegalArgumentException - Thrown if size is not greater than zero, base is not a legal value for a virtual address, or the memory-mapping hardware cannot place the physical memory at the designated address.
In the type parameter description for each constructor that has an Object type parameter, add
"Note that type values are compared by reference (==), not by value (equals)."
In the fourth paragraph of the chapter, replace "schedulable entities" with "schedulable objects"
In semantics for the base scheduler 2, replace
• pparams.setPriority(prio) if t is a schedulable object whose SchedulingParameters is pparams, the
new base priority is prio
• t.setSchedulingParameters(pparams) if t is a schedulable object and pparams is an instance of Priority- Parameters; the new base priority is pparams.getPriority()
• t.setPriority(prio) if t is an instance of java.lang.Thread the new base priority is the lesser of prio, Thread.MAX_PRIORITY, and the maximum priority for t’s thread group. If t is a schedulable object, the new base priority is prio.
with
• pparams.setPriority(prio) if t is a schedulable object with pparams as its SchedulingParameters, where pparams is an instance of PriorityParameters; the new base priority is prio
• t.setSchedulingParameters(pparams) if t is a schedulable object and pparams is an instance of Priority- Parameters; the new base priority is pparams.getPriority()
• t.setPriority(prio) if t is a schedulable object, the new base priority is prio. If it is a Java thread, the new base priority is the lesser of prio, and the maximum priority for t’s thread group.
In the class description's third paragraph, replace
In order for this protocol to have the desired effect in terms of avoiding unbounded priority inversions and preventing deadlock, the
with
The
In the instance(int ceiling) method's IllegalArgumentException description, add, "for the base scheduler"
In the second constructor add
InaccessibleAreaException - Thrown if memory is a scoped memory that is not on the caller’s scope stack.
Fix mis-spellings of InaccessibleAreaException as InnaccessibleAreaException throughout the wait-free queue classes.
In the second constructor add
InaccessibleAreaException - Thrown if memory is a scoped memory that is not on the caller’s scope stack.
In the first constructor, add
java.lang.IllegalArgumentException - Thrown if frequency is less than or equal to zero.
In the second constructor, add "or if frequency is equal to zero." to the IllegalArgumentException description.
In the third constructor, change the IllegalArgumentException description from
java.lang.IllegalArgumentException - If any of the argument values are less than zero.
to
java.lang.IllegalArgumentException - If either of the argument values are less than zero, or if frequency is equal to zero.
Add to the setFrequency(int frequency) method,
java.lang.IllegalArgumentException - Thrown if frequency is less than or equal to zero.
Add method override.
public java.lang.String toString()
Deprecated. 1.0.1
Create a printable string of the time given by this. The string shall be a decimal representation of the frequency, milliseconds and nanosecond values; formatted as follows “(100, 2251 ms, 750000 ns)”
Overrides: toString in class RelativeTime
Returns: String object converted from the time given by this.
To semantic 8, add "(See semantics in the Memory chapter for details.)"
To the constructor, add "IllegalAssignmentError - Thrown if this Timer cannot hold references to handler and clock."
To the addHandler and setHandler methods add "IllegalAssignmentError - Thrown if this AsyncEvent cannot hold a reference to handler."
To the first constructor add "IllegalAssignmentError - Thrown if this OneShotTimer cannot hold a reference to handler."
To the second constructor add "IllegalAssignmentError - Thrown if this OneShotTimer cannot hold references to handler and clock."
To the first constructor add "IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold references to handler and interval."
To the second constructor add "IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold references to handler, clock and interval."
To the setInterval() method add "IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold a reference to interval."
In the getInterval() method replace
Returns: The RelativeTime instance with the value of this timer’s interval.
with
Returns: The RelativeTime instance assigned as this periodic timer’s interval by the constructor or setInterval(RelativeTime).
Add the definition
Interruptible blocking methods. The RTSJ and standard Java methods that are explicitly interruptible by an AIE. The interruptible blocking methods comprise HighResolutionTime.waitForObject(), Object.wait(), Thread.sleep(), RealtimeThread.sleep(), Thread.join(), ScopedMemory.join(), ScopedMemory.joinAndEnter(), RealtimeThread.waitForNextPeriodInterruptible(), WaitFreeWriteQueue.read(), WaitFreeReadQueue.waitForData(), WaitFreeReadQueue.write(), WaitFreeDequeue.blockingRead(), WaitFreeDequeue.blockingWrite() and their overloaded forms.
In Semantics and Requirements for Asynchronous Transfer of Control, semantic 1 replace
An AIE is generated when the fire() method is called on an AIE or the RealtimeThread.interrupt() method is called;
with
An AIE is generated for a given schedulable object, when the fire() method is called on an AIE for which the schedulable object is executing within the doInterruptible() method, or the RealtimeThread.interrupt() method is called
In Semantics and Requirements for Asynchronous Transfer of Control, insert semantic 2 after semantic 1
2. The RealtimeThread.interrupt() method throws the generic AIE at the target real-time thread and has the behaviors defined for Thread.interrupt(). This is the only interaction between the ATC mechanism and the conventional interrupt() mechanism.
In Semantics and Requirements for Asynchronous Transfer of Control, insert semantic 4 after what was semantic 2
4. The generation of an AIE through the fire() mechanism behaves as if it set an asynchronously-interrupted status in the schedulable object. If the schedulable object is blocked within an interruptible blocking method, or invokes an interruptible blocking method, when this asynchronously-interrupted status is set, then the invocation immediately completes by throwing the pending AIE and clearing the asynchronously-interrupted status. When a pending AIE is explicitly cleared then the asynchronously-interrupted status is also cleared.
In the previous semantic 3, replace
Methods which block through mechanisms other than the wait(), sleep(), join(), MemoryArea.join(), MemoryArea.joinAndEnter() or Realtime- Thread.waitForNextPeriodInterruptible() methods,
with
Methods which block through mechanisms other than the interruptible blocking methods,
In Summary of ATC Operation, bullet 3, replace
If control is in one of the wait(), sleep(), or join() methods
with
If control is in an interruptible blocking method
To the addHandler() method, add
IllegalAssignmentError - Thrown if this AsyncEvent cannot hold a reference to handler.
To the fire() method's MITViolationException description, change the first sentence from
Thrown if there is a handler associated with this event that has its MIT violated by the call to fire (and it has set the minimum inter-arrival time violation behavior to MITViolationExcept).
to
Thrown under the base priority scheduler’s semantics if there is a handler associated with this event that has its MIT violated by the call to fire (and it has set the minimum inter-arrival time violation behavior to MITViolationExcept).
To the setHandler method, add
IllegalAssignmentError - Thrown if this AsyncEvent cannot hold a reference to handler.
In the second constructor, change the IllegalArgumentException description from
java.lang.IllegalArgumentException - Thrown if the initial memory area or this is in heap memory, and the nonheap parameter is true.
to
java.lang.IllegalArgumentException - Thrown if this is in heap memory, and nonheap is true.
In the third constructor, change the IllegalArgumentException from
java.lang.IllegalArgumentException - Thrown if the nonheap parameter is true and any parameter, or the AsyncEventHandler instance is in heap memory or the initial memory area is heap memory.
to
java.lang.IllegalArgumentException - Thrown if logic or this is in heap memory, and nonheap is true.
In the third and fourth constructors, add
IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to logic.
In the fifth constructor, change the IllegalArgumentException description from
java.lang.IllegalArgumentException - Thrown if the nonheap parameter is true and any parameter, or the AsyncEventHandler instance is in heap memory or the initial memory area is heap memory.
to
java.lang.IllegalArgumentException - Thrown if nonheap is true and this or any object passed as a parameter is in heap memory. Also thrown if noheap is true and area is heapmemory.
To the fifth constructor, add
IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to area.
In the sixth constructor's description of the release parameter, change "the AEH's" to "this AEH's"
In the sixth constructor's description of the logic parameter, change
logic - The java.lang.Runnable object whose run() method is executed by handleAsyncEvent() .If null, the logic will default to the AEH’s run method.
to
logic - The java.lang.Runnable object whose run() method is executed by handleAsyncEvent()401 . If null, the default handleAsyncEvent() method invokes nothing.
In the sixth constructor's description of the IllegalArgumentException, replace
java.lang.IllegalArgumentException - Thrown if the nonheap parameter is true and any parameter, or the AsyncEventHandler instance is in heap memory or the initial memory area is heap memory.
with
java.lang.IllegalArgumentException - Thrown if nonheap is true and any parameter, or this is in heap memory or area is heap memory.
To the sixth constructor add
IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of area and logic.
In the seventh constructor's description of the IllegalArgumentException, change
java.lang.IllegalArgumentException - Thrown if the initial memory area, logic, any parameter object, or this is in heap memory, and the nonheap parameter is true.
to
java.lang.IllegalArgumentException - Thrown if nonheap is true and logic, any parameter object, or this is in heap memory. Also thrown if noheap is true and area is heap memory.
To the seventh constructor, add
IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of area and logic.
Change "the AEH" to "this AEH" twice in the last paragraph of the getAndClearPendingFireCount(), getAndDecrementPendingFireCount(), and getAndIncrementPendingFireCount() descriptions
In the last paragraph of the getAndIncrementPendingFireCount() description, change "the scheduling" to "the arrival-time queue and the scheduling"
Add to getAndIncrementPendingFireCount()
MITViolationException - Thrown when this AEH is controlled by sporadic scheduling parameters under the base scheduler, the parameters specify the mitViolationExcept policy, and this method would introduce a release that would violate the specified minimum interarrival time.
ArrivalTimeQueueOverflowException - Thrown when this AEH is controlled by aperiodic scheduling parameters under the base scheduler, the release parameters specify the arrivalTimeQueueOverflowExcept policy, and this method would cause the arrival time queue to overflow.
Change the description of handleAsyncEvent() from
This method holds the logic which is to be executed when associated instances of AsyncEvent occur. The default logic is null. If this handler was constructed using an instance of java.lang.Runnable as an argument to the constructor, then that instance’s run() method will be invoked from this method. This method will be invoked repeatedly while fireCount is greater than zero. All throwables from (or propagated through) handleAsyncEvent are caught, a stack trace is printed and execution continues as if handleAsyncEvent had returned normally.
to
This method holds the logic which is to be executed when any AsyncEvent with which this handler is associated is fired. This method will be invoked repeatedly while fireCount is greater than zero. The default implementation of this method invokes the run method of any non-null logic instance passed to the constructor of this handler. If the initial memory area of this AsyncEventHandler is a ScopedMemory, the initial memory area’s reference count does not drop below one between invocations of handleAsyncEvent(). All throwables from (or propagated through) handleAsyncEvent are caught, a stack trace is printed and execution continues as if handleAsyncEvent had returned normally.
Change the description of run() from
Used by the asynchronous event mechanism, see AsyncEvent. This method invokes handleAsyncEvent() repeatedly while the fireCount is greater than zero. Applications cannot override this method and should thus override handleAsyncEvent() in subclasses with the logic of the handler.
to
When used as part of the internal mechanism activated by firing an async event, this method’s detailed semantics are defined by the scheduler associated with this handler. The general outline is:
while (fireCount > 0) {
[initiate release]
fireCount--;
try {
handleAsyncEvent();
} catch (Throwable th){
th.printStackTrace();
}
[effect completion]
}
All throwables from (or propagated through) handleAsyncEvent() are caught, a stack trace is printed and execution continues as if handleAsyncEvent had returned normally.
When it is directly invoked, this method invokes handleAsyncEvent() repeatedly while the fireCount is greater than zero; e.g.,
while (getAndDecrementPendingFireCount() > 0)
handleAsyncEvent();
however direct invocation of run is not recommended as it may interact with the normal release of this handler. Applications cannot override this method and thus should use the logic parameter at construction, or override handleAsyncEvent() in subclasses with the logic of the handler.
In the second constructor's description of the logic parameter, change
logic - The java.lang.Runnable object whose run() method is executed by AsyncEventHandler.handleAsyncEvent(). If null, the logic will default to the BAEH’s run method.
to
logic - The java.lang.Runnable object whose run() method is executed by AsyncEventHandler.handleAsyncEvent(). If null, the default AsyncEventHandler.handleAsyncEvent() method invokes nothing.
Change the second constructor's description of IllegalArgumentException from
java.lang.IllegalArgumentException - Thrown if the initial memory area is in heap memory, and the noheap parameter is true.
to
java.lang.IllegalArgumentException - Thrown if nonheap is true and logic, any parameter object, or this is in heap memory. Also thrown if noheap is true and area is heap memory.
To the second constructor, add
IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to nonnull values of area and logic.
Change the description of the fire() method from
Generate this exception if its doInterruptible() has been invoked and not completed. If this is the only outstanding AIE on the current schedulable object, it becomes the current AIE. Otherwise, it only becomes the current AIE if it is at a less deeper level of nesting compared with the current outstanding AIE.
to
Generate this exception if its doInterruptible() has been invoked and not completed. If this is the only outstanding AIE on the schedulable object that invoked this AIE’s doInterruptible(Interruptible) method, this AIE becomes that schedulable object’s current AIE. Otherwise, it only becomes the current AIE if it is at a less deeper level of nesting compared with the current outstanding AIE.
Change the class description from
If an arrival time occurs and should be queued but the queue already holds a number
of times equal to the initial queue length defined by this then the fire() method shall
throw an instance of this class. If the arrival time is a result of a happening to which
the instance of AsyncEventHandler is bound then the arrival time is ignored.
to
If an arrival time occurs and should be queued but the queue already holds a number
of times equal to the initial queue length defined by this an instance of this class may
be be thrown. If the arrival time is a result of a happening to which the instance of
AsyncEventHandler is bound then the arrival time is ignored.
Change the class description from
The specified memory area is not above the current allocation context on the current thread scope stack.
to
The specified memory area is not on the current thread’s scope stack.
Change the class description from
Thrown by the fire method of an instance of AsyncEvent when on a minimum interarrival time violation. More specifically, it is thrown when:
• any instance of AsyncEventHandler associated with the AsyncEvent has ReleaseParameters from the clas SporadicParameters
• The MIT violation behavior for the async event handler is mitViolationExcept
• The invocation of fire violates the minimum interarrival time constraint.
to
Thrown by the AsyncEvent.fire() or AsyncEventHandler.getAndIncrementPendingFireCount() on a minimum interarrival time violation. More specifically, it is thrown under the semantics of the base priority scheduler’s sporadic parameters’ mitViolationExcept policy when an attempt is made to introduce a release that would violate the MIT constraint.
