javax.realtime

Class AsyncEvent

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

Direct Known Subclasses:

Signal, Timer

public class AsyncEvent
extends AsyncBaseEvent

Jamaica Real-Time Specification for Java class AsyncEvent.

An instance of AsyncEvent binds an external event (a happening) to a set of AbstractAsyncEventHandlers. Whenever the external event is fired, the fire count of all event handlers associated with this event will be increased and the handlers will be released.

Constructor Summary

Constructors

Constructor and Description
AsyncEvent() Constructor constructs a new AsyncEvent that is not bound to any signal.

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) addHandler adds a handler to this event.
void	addHandler(AsyncEventHandler handler) addHandler adds a handler to this event.
void	bindTo(String happening) bindTo bind this handler to a happening that is identified by a platform-dependent string.
ReleaseParameters	createReleaseParameters() createReleaseParameters creates the default release parameters for this event.
void	fire() fire this event once.
boolean	handledBy(AsyncBaseEventHandler handler) handledBy tests if this event is handled by a given handler.
boolean	handledBy(AsyncEventHandler handler) handledBy tests if this event is handled by a given handler.
void	removeHandler(AsyncBaseEventHandler handler) removeHandler removes a handler from this event that was previously added by addHandler.
void	removeHandler(AsyncEventHandler handler) removeHandler removes a handler from this event that was previously added by addHandler.
void	setHandler(AsyncBaseEventHandler handler) setHandler removes all handlers from the list of handlers for this event and adds the given handler.
void	setHandler(AsyncEventHandler handler) setHandler removes all handlers from the list of handlers for this event and adds the given handler.
void	unbindTo(String happening) unbindTo removes the binding to a certain happening.

Methods inherited from class javax.realtime.AsyncBaseEvent

disable, enable, hasHandlers, isRunning

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncEvent

public AsyncEvent()

Constructor constructs a new AsyncEvent that is not bound to any signal.

Method Detail

addHandler

public void addHandler(AsyncBaseEventHandler handler)

addHandler adds a handler to this event. If the handler has already been added, this is a nop.

Since a reference to handler has to be stored in this, an IllegalAssignmentError will be caused if handler is allocated in a memory area that does not permit to be stored in an object allocated in this' memory area.

This call will allocate a small object in the memory area this was allocated in.

The execution of addHandler is atomic with respect to removeHandler and fire.

ensures
(handler != null) ==> (handledBy(handler));

Overrides:

addHandler in class AsyncBaseEvent

Throws:

StaticIllegalArgumentException - if handler == null;

Parameters:

handler - the new handler.

Since:

RTSJ 2.0

addHandler

public void addHandler(AsyncEventHandler handler)

addHandler adds a handler to this event. If the handler has already been added, this is a nop.

This method has been replaced in RTSJ 2.0 to support the more generic AsyncBaseEventHandler and is kept for binary compatibility.

See Also:

addHandler(AsyncBaseEventHandler)

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

removeHandler removes a handler from this event that was previously added by addHandler.

The execution of removeHandler is atomic with respect to addHandler, setHandler, handledBy, and fire.

ensures
((handler == null) || !handledBy(handler));

Overrides:

removeHandler in class AsyncBaseEvent

Parameters:

handler - the handler to be removed. If this handler is null or has not been added to this event, nothing will happen.

Since:

RTSJ 2.0

removeHandler

public void removeHandler(AsyncEventHandler handler)

removeHandler removes a handler from this event that was previously added by addHandler.

This method has been replaced in RTSJ 2.0 to support the more generic AsyncBaseEventHandler and is kept for binary compatibility.

See Also:

removeHandler(AsyncBaseEventHandler)

handledBy

public boolean handledBy(AsyncBaseEventHandler handler)

handledBy tests if this event is handled by a given handler.

Overrides:

handledBy in class AsyncBaseEvent

Parameters:

handler - The handler, may be null.

Returns:

true iff handler is not null and added as a handler for this event.

handledBy

public boolean handledBy(AsyncEventHandler handler)

handledBy tests if this event is handled by a given handler. This method has been replaced in RTSJ 2.0 to support the more generic AsyncBaseEventHandler and is kept for binary compatibility.

See Also:

handledBy(AsyncBaseEventHandler)

setHandler

public void setHandler(AsyncBaseEventHandler handler)

setHandler removes all handlers from the list of handlers for this event and adds the given handler.

The execution of setHandler is atomic with respect to addHandler, removeHandler, handledBy, and fire.

ensures
((handler == null) || handledBy(handler));

Overrides:

setHandler in class AsyncBaseEvent

Parameters:

handler - The handler to be added, null if none.

setHandler

public void setHandler(AsyncEventHandler handler)

setHandler removes all handlers from the list of handlers for this event and adds the given handler. This method has been replaced in RTSJ 2.0 to support the more generic AsyncBaseEventHandler and is kept for binary compatibility.

See Also:

setHandler(AsyncBaseEventHandler)

createReleaseParameters

public ReleaseParameters createReleaseParameters()

createReleaseParameters creates the default release parameters for this event. The default implementation creates AperiodicParameters without cost/ deadline and without overrun or miss handler.

Overrides:

createReleaseParameters in class AsyncBaseEvent

Returns:

An instance of ReleaseParameters appropriate for handlers for this event.

bindTo

public void bindTo(String happening)
            throws UnknownHappeningException

bindTo bind this handler to a happening that is identified by a platform-dependent string. Integer numbers 1 through POSIXSignalHandler.MAX_SIGNAL_NR bind this event to the corresponding POSIX event.

When this is allocated in ScopedMemory, then the reference count of MemoryArea.getMemoryArea(this) is incremented until this will be unbound from the happening.

Throws:

StaticIllegalArgumentException - if happening is null.

UnknownHappeningException - if happening is not supported.

Parameters:

happening - A platform-dependent string to identify the happening that causes this event.

unbindTo

public void unbindTo(String happening)
              throws UnknownHappeningException

unbindTo removes the binding to a certain happening.

When this is allocated in ScopedMemory, then the reference count of MemoryArea.getMemoryArea(this) is decremented.

Throws:

StaticIllegalArgumentException - if happening is null.

UnknownHappeningException - if happening is not supported or it was not bound to this event via bindTo().

Parameters:

happening - A platform-dependent string to identify the happening that causes this event.

fire

public void fire()
          throws MITViolationException,
                 ArrivalTimeQueueOverflowException

fire this event once. All event handlers that were added to this event will be released. If this event is bound to an external happening, it may still be fired manually by a call to this method.

If one or several handlers released by the call to fire cause an ArrivalTimeQueueOverflowException, all the handlers not affected by the exception will still be released normally.

If the release of the handlers requires both, a MITViolationException (due to a handler with SporadicParameters) and an ArrivalTimeQueueOverflowException, this method will throw the MITViolationException.

Throws:

MITViolationException

ArrivalTimeQueueOverflowException