javax.realtime
Class AsyncEvent

java.lang.Object
  javax.realtime.AsyncEvent

Direct Known Subclasses:

Timer

public class AsyncEvent

extends java.lang.Object

An asynchronous event represents something that can happen, like a light turning red. It can have a set of handlers associated with it, and when the event occurs, the handler is scheduled by the scheduler to which it holds a reference (see AsyncEventHandler and Scheduler).

A major motivator for this style of binding events is that we expect to have lots of events and lots of event handlers. An event handler is logically very similar to a thread, but it is intended to have a much lower cost (in both time and space) --- assuming that a relatively small number of events are fired and in the process of being handled at once. AsyncEvent.fire() differs from a method call because the handler (a) has scheduling parameters and (b) is executed asynchronously.

Field Summary

protected java.util.Set

handlers The set of handlers for this AsyncEvent

Constructor Summary

AsyncEvent()
Void constructor.

Method Summary

void	addHandler(AsyncEventHandler handler) Add a handler to the set of handlers associated with this event.
void	bindTo(java.lang.String happening) Binds this to an external event, a happening.
ReleaseParameters	createReleaseParameters() Create a ReleaseParameters object appropriate to the release characteristics of this event.
void	fire() Fire this instance of AsyncEvent.
boolean	handledBy(AsyncEventHandler handler) Test to see if the handler given as the parameter is associated with this.
void	removeHandler(AsyncEventHandler handler) Remove a handler from the set associated with this event.
void	setHandler(AsyncEventHandler handler) Associate a new handler with this event and remove all existing handlers.
void	unbindTo(java.lang.String happening) Removes a binding to an external event, a happening.

Methods inherited from class java.lang.Object

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

Field Detail

handlers

protected java.util.Set handlers

The set of handlers for this AsyncEvent

Constructor Detail

AsyncEvent

public AsyncEvent()

Void constructor.

Method Detail

addHandler

public void addHandler(AsyncEventHandler handler)

Add a handler to the set of handlers associated with this event. An instance of AsyncEvent may have more than one associated handler. However, adding a handler to an event has no effect if the handler is already attached to the event.

The execution of this method is atomic with respect to the execution of the fire() method.

Since this affects the constraints expressed in the release parameters of an existing schedulable object, this may change the feasibility of the current system. This method does not change feasibility set of any scheduler, and no feasibility test is performed.

Note, 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.

If the handler is already associated with the event, the call has no effect.

Throws:

java.lang.IllegalArgumentException - Thrown if handler is null.

bindTo

public void bindTo(java.lang.String happening)
            throws UnknownHappeningException

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 if 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 real-time 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 - if the happening string is not supported by the system

UnknownHappeningException

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.

If an event returns PeriodicParameters, there is no requirement for an implementation to check that the handler is released periodically.

Returns:

A new ReleaseParameters object.

fire

public void fire()

Fire this instance of AsyncEvent. The asynchronous event handlers associated with this event will be released. If no handlers are attached then the method does nothing. An AsyncEvent that has been bound to an external happening can still be fired by the application code.

• If the instance of AsyncEvent has more than one instance of AsyncEventHandler with release parameters object of type AperiodicParameters attached and the execution of AsyncEvent.fire() introduces the requirement to throw at least one type of exception, then all instances of AsyncEventHandler not affected by the exception are handled normally.
• If the instance of AsyncEvent has more than one instance of AsyncEventHandler with release parameters object of type SporadicParameters attached and the execution of AsyncEvent.fire() introduces the simultaneous requirement to throw more than one type of exception or error then MITViolationException has precedence over ArrivalTimeQueueOverflowException.

Throws:

MITViolationException - 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). Only the handlers which do not have their MITs violated are released in this situation.

ArrivalTimeQueueOverflowException - Thrown if the queue of arrival time information overflows. Only the handlers which do not cause this exception to be thrown are released in this situation.

handledBy

public boolean handledBy(AsyncEventHandler 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 if the parameter is associated with this. False if handler is null or the parameters is not associated with this.

removeHandler

public void removeHandler(AsyncEventHandler handler)

Remove a handler from the set associated with this event. The execution of this method is atomic with respect to the execution of the fire() method.

A removed handler continues to execute until its fireCount becomes zero and it completes.

Since this affects the constraints expressed in the release parameters of an existing schedulable object, this may change the feasibility of the current system. This method does not change the feasibility set of any scheduler, and no feasibility test is performed.

Parameters:

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

setHandler

public void setHandler(AsyncEventHandler handler)

Associate a new handler with this event and remove all existing handlers. The execution of this method is atomic with respect to the execution of the fire() method.

Since this affects the constraints expressed in the release parameters of the existing schedulable objects, this may change the feasibility of the current system. This method does not change the feasibility set of any scheduler, and no feasibility test is performed.

Parameters:

handler - The new instance of AsyncEventHandler to be associated with this. If handler is null then no handler will be associated with this (i.e., remove all handlers).

unbindTo

public void unbindTo(java.lang.String happening)
              throws UnknownHappeningException

Removes a binding to an external event, a happening. The meaningful values of happening are implementation dependent. If 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 - Thrown if this instance of AsyncEvent is not bound to the given happening or the given happening is not supported by the implementation.

java.lang.IllegalArgumentException - Thrown if happening is null.