javax.realtime

Class AsyncEvent

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

Direct Known Subclasses:

Happening, Signal, Timer

public class AsyncEvent
extends AsyncBaseEvent

An asynchronous event can have a set of handlers associated with it, and when the event occurs, the fireCount of each handler is incremented, and the handlers are released (see AsyncEventHandler).

Since:

RTSJ 2.0 extends AsyncBaseEvent

Constructor Summary

Constructors

Constructor and Description
AsyncEvent() Creates a new AsyncEvent object.

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncEventHandler handler) Deprecated. since RTSJ 2.0, replaced by AsyncBaseEvent.addHandler(AsyncBaseEventHandler)
void	bindTo(java.lang.String happening) Deprecated. since RTSJ 2.0
void	fire() When enabled, release the asynchronous event handlers associated with this instance of AsyncEvent.
boolean	handledBy(AsyncEventHandler handler) Deprecated. since RTSJ 2.0, replaced by AsyncBaseEvent.handledBy(AsyncBaseEventHandler)
void	removeHandler(AsyncEventHandler handler) Deprecated. since RTSJ 2.0
void	setHandler(AsyncEventHandler handler) Deprecated. since RTSJ 2.0
void	unbindTo(java.lang.String happening) Deprecated. since RTSJ 2.0

Methods inherited from class javax.realtime.AsyncBaseEvent

addHandler, createReleaseParameters, disable, enable, handledBy, hasHandlers, isRunning, removeHandler, setHandler

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncEvent

public AsyncEvent()

Creates a new AsyncEvent object.

Method Detail

fire

public void fire()

When enabled, release the asynchronous event handlers associated with this instance of AsyncEvent. When this object is disabled the method does nothing, i.e., it skips the release. When no handlers are attached, the release is ignored. This method does not suspend itself and has a runtime complexity of O(n), where n is the number of attached handers. For an instance of AsyncEvent that has more than one instance of AsyncEventHandler,

• when one of these handlers throws an exception, all instances of AsyncEventHandler not affected by the exception must be released normally before the exception is propagated, and
• when more than one of these handlers throws an exception, the propagation of MITViolationException has precedence over ArrivalTimeQueueOverflowException, which has precedence over all others.

The later case can only occur when more than one of the handlers has a release parameters instance of type SporadicParameters, since only them can MITViolationException and ArrivalTimeQueueOverflowException be thrown.

Throws:

MITViolationException - under the base priority scheduler's semantics when there is a handler associated with this event that has its MIT violated by the call to fire (and it has set the minimum interarrival time violation behavior to MITViolationExcept). Only the handlers which do not have their MITs violated are released in this situation.

ArrivalTimeQueueOverflowException - when the queue of release information, arrival time and payload, overflows. Only the handlers which do not cause this exception to be thrown are released in this situation. When fire is called from the infrastructure, such as for an ActiveEvent, this exception is ignored.

handledBy

@Deprecated
public boolean handledBy(AsyncEventHandler handler)

Deprecated. since RTSJ 2.0, replaced by AsyncBaseEvent.handledBy(AsyncBaseEventHandler)

Determines whether or not the handler given as the parameter is associated with this.

Parameters:

handler - The handler to be tested to determine its association with this.

Returns:

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

addHandler

@Deprecated
public void addHandler(AsyncEventHandler handler)

Deprecated. since RTSJ 2.0, replaced by AsyncBaseEvent.addHandler(AsyncBaseEventHandler)

Adds 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.

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.

Throws:

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

IllegalAssignmentError - when this AsyncEvent cannot hold a reference to 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.

setHandler

@Deprecated
public void setHandler(AsyncEventHandler handler)

Deprecated. since RTSJ 2.0

Replaced by AsyncBaseEvent.setHandler(AsyncBaseEventHandler)

Parameters:

handler - For becoming the sole handler for this.

removeHandler

@Deprecated
public void removeHandler(AsyncEventHandler handler)

Deprecated. since RTSJ 2.0

Replaced by AsyncBaseEvent.removeHandler(AsyncBaseEventHandler)

Parameters:

handler - For removal.

bindTo

@Deprecated
public void bindTo(java.lang.String happening)

Deprecated. since RTSJ 2.0

Binds this to an external event, a happening. The meaningful values of happening are implementation dependent. This instance of AsyncEvent is considered to have occurred whenever the happening is triggered. More than one happening can be bound to the same AsyncEvent. However, binding a happening to an event has no effect when the happening is already bound to the event.

When an event, which is declared in a scoped memory area, is bound to an external happening, the reference count of that scoped memory area is incremented (as if there is an external realtime thread accessing the area). The reference count is decremented when the event is unbound from the happening.

Parameters:

happening - An implementation-dependent value that binds this instance of AsyncEvent to a happening.

Throws:

UnknownHappeningException - when the String value is not supported by the implementation.

StaticIllegalArgumentException - when happening is null.

unbindTo

@Deprecated
public void unbindTo(java.lang.String happening)

Deprecated. since RTSJ 2.0

Removes a binding to an external event, a happening. The meaningful values of happening are implementation dependent. When the associated event is declared in a scoped memory area, the reference count for the memory area is decremented.

Parameters:

happening - An implementation-dependent value representing some external event to which this instance of AsyncEvent is bound.

Throws:

UnknownHappeningException - when this instance of AsyncEvent is not bound to the given happening or the given happening is not supported by the implementation.

StaticIllegalArgumentException - when happening is null.