javax.realtime
Class AsyncEvent

java.lang.Object
  javax.realtime.AsyncEvent

Direct Known Subclasses:

Timer

public class AsyncEvent

extends 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 building 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.

Author:

Angelo Corsaro, Morgan Deters

Field Summary

protected PriorityQueue

handlerList

Constructor Summary

AsyncEvent()
Construct a new AsyncEvent.

Method Summary

void	addHandler(AsyncEventHandler handler) Add a handler to the set of handlers associated with this event.
void	bindTo(String happening) Binds this to an external event (a happening).
ReleaseParameters	createReleaseParameters() Create a ReleaseParameters block appropriate to the release characteristics of this event.
void	fire() Fire this event.
boolean	handledBy(AsyncEventHandler handler) Returns true if and only if this event is handled by the passed handler.
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, removing all existing handlers.
void	unbindTo(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

handlerList

protected PriorityQueue handlerList

Constructor Detail

AsyncEvent

public AsyncEvent()

Construct a new AsyncEvent.

Method Detail

addHandler

public void addHandler(AsyncEventHandler handler)

Add a handler to the set of handlers associated with this event. An AsyncEvent may have more than one associated handler. Adding a handler to an AsyncEvent to which it is already attached has no effect. 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 schedule; however, this method does not cause any feasibility test to be performed, nor is any scheduler's feasibility set updated.

An assignment from this to the handler must be valid in accordance with RTSJ memory assignment rules.

Parameters:

handler - the new handler to add to the list of handlers already associated with this

Throws:

IllegalArgumentException - if handler is null

removeHandler

public void removeHandler(AsyncEventHandler handler)

Remove a handler from the set associated with this event. 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.

Parameters:

handler - the handler to be dissociated from this; if null, nothing happens; if not already associated with this, nothing happens.

handledBy

public boolean handledBy(AsyncEventHandler handler)

Returns true if and only if this event is handled by the passed handler.

Parameters:

handler - an AsyncEventHandler for which to test

Returns:

true if this event is handled by the given handler

setHandler

public void setHandler(AsyncEventHandler handler)

Associate a new handler with this event, removing all existing handlers. 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 schedule. This method does not cause any feasibility test to be performed, nor is any scheduler's feasibility set updated.

Parameters:

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

createReleaseParameters

public ReleaseParameters createReleaseParameters()

Create a ReleaseParameters block 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 ReleaseParameters for which it knows values, like cost. The returned ReleaseParameters object is not bound to the event. Any changes in the event's ReleaseParameters are not reflected in previously returned objects.

Returns:

a ReleaseParameters value

bindTo

public void bindTo(String happening)
            throws UnknownHappeningException

Binds this to an external event (a happening). The meaningful values of happening are implementation dependent. This AsyncEvent is considered to have occurred whenever the external event occurs. More than one happening can be bound to the same AsyncEvent. If a happening is already bound to an event, binding it again has no effect.

When an event allocated in a ScopedMemory area is bound to an external happening, the reference count of that memory area is incremented. The reference count is decremented when the event is unbound from the happening.

Parameters:

happening - an implementation-dependent value that binds this AsyncEvent to some external event

Throws:

UnknownHappeningException - the happening string is not supported by the system

IllegalArgumentException - happening is null

unbindTo

public void unbindTo(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 memory area's reference count is decremented.

Parameters:

happening - an implementation-dependent value representing some external event to which this AsyncEvent is to be unbound

Throws:

UnknownHappeningException - this AsyncEvent is not bound to the given happening, or the happening string is not supported by the system

IllegalArgumentException - happening is null

fire

public void fire()

Fire this event. If no handlers are attached, nothing happens.

If this method could throw both types of exceptions, it will throw an MITViolationException.

Implementation Detail: As currently implemented this method has linear time complexity in the number of registered handlers.

Throws:

MITViolationException - there is a handler associated with this event that has its MIT violated (and it has MITViolationExcept behavior); handlers which cause this exception to be thrown are not released, but all others are

ArrivalTimeQueueOverflowException - if the queue of arrival time information overflows; handlers which cause this exception to be thrown are not released, but all others are