javax.realtime

Class AsyncBaseEvent

java.lang.Object

javax.realtime.AsyncBaseEvent

Direct Known Subclasses:

AsyncEvent, AsyncLongEvent, AsyncObjectEvent

public abstract class AsyncBaseEvent
extends Object

This is the base class for all asynchronous events, where asynchronous is in regards to running code, not external time. This class unifies the original AsyncEvent with AsyncLongEvent.

Note that when this class is collected, all its handlers are automatically removed as if setHandler(javax.realtime.AsyncBaseEventHandler) was called with a null parameter.

Since:

RTSJ 2.0

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Add a handler to the set of handlers associated with this event.
ReleaseParameters<?>	createReleaseParameters() Create a ReleaseParameters object appropriate to the release characteristics of this event.
void	disable() Change the state of the event so that the associated handlers are skipped on fire.
void	enable() Change the state of the event so that associated handlers are released on fire.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
boolean	handledBy(AsyncBaseEventHandler handler) Test to see if the handler given as the parameter is associated with this.
boolean	hasHandlers() Determine whether or not this event has any handlers.
boolean	isRunning() Determine the firing state (releasing or skipping) of this event, i.e, whether it is enabled or disabled
void	removeHandler(AsyncBaseEventHandler handler) Remove a handler from the set associated with this event.
void	setHandler(AsyncBaseEventHandler handler) Associate a new handler with this event and remove all existing handlers.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addHandler

public void addHandler(AsyncBaseEventHandler handler)

Add a handler to the set of handlers associated with this event. An instance of AsyncBaseEvent may have more than one associated handler. However, adding a handler to an event has no effect when the handler is already attached to the event The execution of this method is atomic with respect to the execution of the fire() method. Note that there is an implicit reference to the handler stored in this. The assignment must be valid under any applicable memory assignment rules.

Throws:

StaticIllegalArgumentException - when handler is null or the handler has PeriodicParameters

IllegalAssignmentError - when this AsyncBaseEvent cannot hold a reference to this handler

StaticIllegalStateException - when the configured scheduler and SchedulingParameters for handler are not compatible with one another

ScopedCycleException - when handler has an explicit initial scoped memory area that has already been entered from a memory area other than the area where handler was allocated

Parameters:

handler - The new handler to add to the list of handlers already associated with this. When handler is already associated with the event, the call has no effect

setHandler

public void setHandler(AsyncBaseEventHandler handler)

Associate a new handler with this event and remove all existing handlers.

Throws:

StaticIllegalArgumentException - when handler has PeriodicParameters. Only the subclass PeriodicTimer is allowed to have handlers with PeriodicParameters

IllegalAssignmentError - when this AsyncBaseEvent cannot hold a reference to handler

Parameters:

handler - The instance of AsyncBaseEventHandler to be associated with this. When handler is null then no handler will be associated with this, i.e., behave effectively as if setHandler(null) invokes removeHandler(AsyncBaseEventHandler) for each associated handler.

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

Remove a handler from the set associated with this event. A removed handler continues to execute until its fireCount becomes a zero and it completes. When handler has a scoped non-default initial memory area and execution of this method causes handler to become unfirable this method shall not return until all related finalization has completed

Parameters:

handler - The handler to be disassociated from this. When null nothing happens. When the handler is not already associated with this then nothing happens

hasHandlers

public boolean hasHandlers()

Determine whether or not this event has any handlers.

Returns:

true iff at least one handler is associated with this event

enable

public void enable()

Change the state of the event so that associated handlers are released on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method enables that request mechanism

disable

public void disable()

Change the state of the event so that the associated handlers are skipped on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method disables that request mechanism

isRunning

public boolean isRunning()

Determine the firing state (releasing or skipping) of this event, i.e, whether it is enabled or disabled

Returns:

true when releasing, false when skipping

handledBy

public boolean handledBy(AsyncBaseEventHandler handler)

Test to see if the handler given as the parameter is associated with this.

Parameters:

handler - The handler to be tested to determine if it is associated with this.

Returns:

true when the parameter is associated with this. false when the handler is null or the parameters is not associated with this

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()

Create a ReleaseParameters object appropriate to the release characteristics of this event. The default is the most pessimistic AperiodicParameters. This is typically called by code that is setting up a handler for this event that will fill in the parts of the release parameters for which it has values, e.g.,cost. The returned ReleaseParameters object is not bound to the event. Any changes in the event's release parameters are not reflected in previously returned objects. When an event returns PeriodicParameters, there is no requirement for an implementation to check that the handler is released periodically

Throws:

StaticUnsupportedOperationException - always, since it is not yet implemented.

Returns:

a new ReleaseParameters object

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

JamaicaVM: Realtime code requires special care when using finalize:

NOTE: The use of finalize() is strongly discouraged for realtime or safety-critical code. This method should only be used for debugging purposes. If used as a last resort to reclaim non-memory resources, finalize() should indicate the resource leak with a loud error message.

There is no guarantee that finalize() will be called, the memory management may decide not to reclaim this object's memory or to delay the call to finalize() to an unspecified point in time. It is therefore recommended never to use the finalize method to release any resources (files, network connections, non-Java memory, etc.) since releasing of these resource may be delayed perpetually.

The order of finalization is not specified, i.e., the finalize method of any two objects that become unreachable may be called in an arbitrary order. It therefore has to be assumed that when finalize() is called on an object, that the finalize() method of any object that is only reachable through this object() has been called as well or is called simultaneously by another thread.

The presence of a finalize-method in any sub-class of Object causes the reclamation of the memory of this object to be delayed until the finalize() method has been executed. The finalize() method is typically executed by the finalizer thread (that may run at a low priority) or by a call to Runtime.runFinalization().

Any code sequence that creates instances of a class that defines a finalize() method must therefore ensure that sufficient CPU time is allocated to the finalizer thread or that Runtime.runFinalization() is called regularly such that the finalize() methods can be executed and the object's memory can be reclaimed.

The finalize method itself should never block or run for long times since it would otherwise block the finalizer thread or the thread that called Runtime.runFinalization() and prevent the execution other finalize() method and consequently prevent the reclamation of these object's memory.

For objects that are allocated in a javax.realtime.memory.ScopedMemory, the finalize() methods will be called when this scoped memory is exited by the last thread. Unlike HeapMemory, which is controlled by the garbage collector, ScopedMemory provides a defined execution point for the finalize() mehods and it is therefore safer to use finalize() here.

Overrides:

finalize in class Object

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference