javax.realtime.device

Class Happening

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

javax.realtime.device.Happening

All Implemented Interfaces:

ActiveEvent<Happening,HappeningDispatcher>, Releasable<Happening,HappeningDispatcher>

public class Happening
extends AsyncEvent
implements ActiveEvent<Happening,HappeningDispatcher>

This class provides second level handling for external events such as interrupts. A happening can be triggered by an interrupt service routine or from native code. Application-defined Happenings can be identified by an application-provided name or a system-provided id, both of which must be unique. A system Happening has a name provided by the system which is a string beginning with @.

Since:

RTSJ 2.0

Constructor Summary

Constructors

Constructor and Description
Happening(String name) Creates a happening with the given name and the default dispatcher.
Happening(String name, HappeningDispatcher dispatcher) Creates a happening with the given name.

Method Summary

Modifier and Type	Method and Description
static int	createId(String name) Sets up a mapping between a name and a system-dependent ID.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
static Happening	get(int id) Gets the external event corresponding to a given id.
static Happening	get(String name) Gets the external event corresponding to a given name.
HappeningDispatcher	getDispatcher() Obtain the current dispatcher for this event.
static Happening	getHappening(String name) Finds an active happening by its name.
int	getId() Gets the number of this happening.
static int	getId(String name) Obtains the ID of name, when one exists or -1, when name is not registered.
String	getName() Gets the name of this happening.
boolean	isActive() Determines the activation state of this happening, i.e., when it has been started.
static boolean	isHappening(String name) Determines whether or not there is an active happening with name given as parameter.
boolean	isRunning() Determines the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.
HappeningDispatcher	setDispatcher(HappeningDispatcher dispatcher) Change the current dispatcher for this event.
void	start() Starts this happening, i.e., changes its state to the active and enabled.
void	start(boolean disabled) Starts this happening, but leaves it in the disabled state.
boolean	stop() Stops this happening from responding to the fire and trigger methods.
void	trigger() Causes the event dispatcher associated with this to be scheduled for execution.
static boolean	trigger(int id) Causes the event dispatcher corresponding to happeningId to be scheduled for execution.

Methods inherited from class javax.realtime.AsyncEvent

addHandler, bindTo, createReleaseParameters, fire, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

Constructor Detail

Happening

public Happening(String name,
                 HappeningDispatcher dispatcher)
          throws StaticIllegalArgumentException

Creates a happening with the given name.

Throws:

StaticIllegalArgumentException - when name is null or does not match the pattern full identifier naming convention, i.e., package plus name. An implementation may throw this exception for all names starting with java. and javax.

Parameters:

name - A string to name the happening.

dispatcher - To use when being triggered.

Happening

public Happening(String name)
          throws StaticIllegalArgumentException

Creates a happening with the given name and the default dispatcher.

Throws:

StaticIllegalArgumentException - when name is null or does not match the pattern full type naming convention, i.e., package plus name. An implementation may throw this exception for all names starting with java. and javax.

Parameters:

name - A string to name the happening.

Method Detail

getHappening

public static Happening getHappening(String name)

Finds an active happening by its name.

Throws:

StaticIllegalArgumentException - when name is null.

Parameters:

name - Identifies the happening to get.

Returns:

a reference to the happening with the given name, or null, if no happening with the given name is found.

isHappening

public static boolean isHappening(String name)

Determines whether or not there is an active happening with name given as parameter.

Throws:

StaticIllegalArgumentException - when name is null.

Parameters:

name - A string that might name an active happening.

Returns:

true only when there is a registered happening with the given name.

createId

public static int createId(String name)
                    throws StaticIllegalStateException

Sets up a mapping between a name and a system-dependent ID. This can be called either in native code that sets up an interrupt service routine to link it with a happening. Once created, it cannot be removed.

This must take no more than linear time in the number of ID (n) registered, but should be O(log2(n)).

Throws:

StaticIllegalStateException - when name is already registered.

StaticIllegalArgumentException - when name is null.

Parameters:

name - A string to name a happening.

Returns:

an ID assigned by the system.

getId

public static int getId(String name)

Obtains the ID of name, when one exists or -1, when name is not registered.

This must take no more than linear time in the number of ID (n) registered, but should be O(log2(n)).

Throws:

StaticIllegalArgumentException - when name is null.

Parameters:

name - A happening name string.

Returns:

The ID, or -1 when no happening is found with that name.

get

public static Happening get(int id)

Gets the external event corresponding to a given id.

Parameters:

id - The identifier of a registered signal.

Returns:

the signal corresponding to id.

get

public static Happening get(String name)

Gets the external event corresponding to a given name.

Throws:

StaticIllegalArgumentException - when name is null.

Parameters:

name - The name of a registered signal.

Returns:

the signal corresponding to name.

trigger

public static boolean trigger(int id)

Causes the event dispatcher corresponding to happeningId to be scheduled for execution. The implementation should be simple enough so that it can be done in the context of an interrupt service routine.

trigger() and any native code analog to it interact with other ActiveEvent code effectively as if trigger() signals a POSIX counting semaphore that the happening is waiting on.

The implementation is encouraged to create (and document) a native code analog to this method that can be used without a Java context.

This method must execute in constant time.

Parameters:

id - Identifies which happening to trigger.

Returns:

true when a happening with ID happeningId was found, false otherwise.

getId

public final int getId()

Gets the number of this happening.

Returns:

the happening number or -1, when not registered.

getName

public String getName()

Gets the name of this happening.

Returns:

the name of this happening.

isActive

public boolean isActive()

Determines the activation state of this happening, i.e., when it has been started.

Specified by:

isActive in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

true when active; false otherwise.

isRunning

public boolean isRunning()

Determines the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.

Specified by:

isRunning in interface ActiveEvent<Happening,HappeningDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true when releasing, false when skipping.

start

public void start()
           throws StaticIllegalStateException

Starts this happening, i.e., changes its state to the active and enabled. Once a happening is started for the first time, when it is in a scoped memory it increments the scope count of that scope; otherwise, it becomes a member of the root set. An active and enabled happening dispatches its handlers when fired.

Specified by:

start in interface ActiveEvent<Happening,HappeningDispatcher>

Throws:

StaticIllegalStateException - when this happening has already been started or its name is already in use by another happening that has been started.

See Also:

stop()

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this happening, but leaves it in the disabled state. When fired before being enabled, it does not dispatch its handlers.

Specified by:

start in interface ActiveEvent<Happening,HappeningDispatcher>

Throws:

StaticIllegalStateException - when this happening has already been started.

Parameters:

disabled - true for starting in a disabled state.

See Also:

stop()

stop

public boolean stop()
             throws StaticIllegalStateException

Stops this happening from responding to the fire and trigger methods.

Specified by:

stop in interface ActiveEvent<Happening,HappeningDispatcher>

Throws:

StaticIllegalStateException - when this happening is not active.

Returns:

true when this is in the enabled state; false otherwise.

trigger

public void trigger()

Causes the event dispatcher associated with this to be scheduled for execution. The implementation should be simple enough so that it can be done in the context of an interrupt service routine.

This method must execute in constant time.

getDispatcher

public HappeningDispatcher getDispatcher()

Description copied from interface: ActiveEvent

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<Happening,HappeningDispatcher>

Specified by:

getDispatcher in interface Releasable<Happening,HappeningDispatcher>

Returns:

the dispatcher associated with this event.

setDispatcher

public HappeningDispatcher setDispatcher(HappeningDispatcher dispatcher)

Description copied from interface: ActiveEvent

Change the current dispatcher for this event. When dispatcher is null, the default dispatcher is restored.

Specified by:

setDispatcher in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

the dispatcher associated with this event.

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 AsyncBaseEvent

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference