javax.realtime.posix

Class Signal

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

javax.realtime.posix.Signal

All Implemented Interfaces:

ActiveEvent<Signal,SignalDispatcher>, Releasable<Signal,SignalDispatcher>

public final class Signal
extends AsyncEvent
implements ActiveEvent<Signal,SignalDispatcher>

A ActiveEvent subclass for defining a POSIX signal.

Since:

RTSJ 2.0

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Add a handler to the set of handlers associated with this event.
static Signal	get(int id) Gets a supported signal by its ID.
static Signal	get(String name) Gets a supported signal by its name.
SignalDispatcher	getDispatcher() Obtain the current dispatcher for this event.
int	getId() Gets the number of this signal.
static int	getId(String name) Gets the ID of a supported signal by its name.
String	getName() Gets the name of this signal.
static long	getProcessId() Obtains the OS Id of the JVM process.
int	hashCode() Returns a hash code value for the object.
boolean	isActive() Determines the activation state of this signal, i.e., whether or not it has been started.
boolean	isRunning() Determines the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.
static boolean	isSignal(int id) Determines if the given name represents a POSIX signal.
static boolean	isSignal(String name) Determines if a signal with a given name is registered.
void	removeHandler(AsyncBaseEventHandler handler) Remove a handler from the set associated with this event.
void	send(long pid) Sends this signal to another process.
SignalDispatcher	setDispatcher(SignalDispatcher value) Change the current dispatcher for this event.
void	setHandler(AsyncBaseEventHandler handler) Associate a new handler with this event and remove all existing handlers.
void	start() Starts this Signal, i.e., changes to a running state.
void	start(boolean disabled) Starts this Signal, i.e., changes to a running state.
boolean	stop() Stops this Signal.
String	toString() Returns a string representation of the object.
void	trigger()

Methods inherited from class javax.realtime.AsyncEvent

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

Methods inherited from class javax.realtime.AsyncBaseEvent

disable, enable, finalize, handledBy, hasHandlers

Methods inherited from class java.lang.Object

clone, equals, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

Method Detail

isSignal

public static boolean isSignal(String name)

Determines if a signal with a given name is registered.

Parameters:

name - The string passed as the name of the signal.

Returns:

true when a signal with the given name is registered.

isSignal

public static boolean isSignal(int id)

Determines if the given name represents a POSIX signal.

Parameters:

id - The int passed as the numerical identifier of the signal.

Returns:

true when a signal with the given id is defined, but in all other cases false.

getId

public static int getId(String name)

Gets the ID of a supported signal by its name.

Throws:

POSIXInvalidSignalException - when no signal with the given name exists or name is null.

Parameters:

name - The name of the signal for which to search.

Returns:

the ID of the signal named by name.

get

public static Signal get(String name)

Gets a supported signal by its name.

Throws:

POSIXInvalidSignalException - when no signal with the given name exists or name is null.

Parameters:

name - The name identifying the signal to get.

Returns:

the registered signal associated with name or null.

get

public static Signal get(int id)

Gets a supported signal by its ID.

Throws:

POSIXInvalidSignalException - when no signal with the given identifier id exists.

Parameters:

id - The identifier of a registered signal.

Returns:

the signal corresponding to ID or null.

getProcessId

public static long getProcessId()

Obtains the OS Id of the JVM process. When running in kernel space, the result is VM dependent and must be documented. This number returned is only usable with send(long).

Returns:

the OS process ID.

trigger

public void trigger()

getId

public int getId()

Gets the number of this signal.

Returns:

the signal number.

hashCode

public int hashCode()

Description copied from class: Object

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

getName

public String getName()

Gets the name of this signal.

Returns:

the name of this signal.

getDispatcher

public SignalDispatcher getDispatcher()

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<Signal,SignalDispatcher>

Specified by:

getDispatcher in interface Releasable<Signal,SignalDispatcher>

Returns:

the dispatcher associated with this event.

setDispatcher

public SignalDispatcher setDispatcher(SignalDispatcher value)

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

Specified by:

setDispatcher in interface ActiveEvent<Signal,SignalDispatcher>

Returns:

the dispatcher associated with this event.

isActive

public boolean isActive()

Determines the activation state of this signal, i.e., whether or not it has been started.

Specified by:

isActive in interface ActiveEvent<Signal,SignalDispatcher>

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<Signal,SignalDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true when releasing, false when skipping.

toString

public String toString()

Description copied from class: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.

start

public void start()
           throws StaticIllegalStateException

Starts this Signal, i.e., changes to a running state. A running signal is a source of activation when in a scoped memory and is a member of the root set when in the heap. A running signal can be triggered.

Specified by:

start in interface ActiveEvent<Signal,SignalDispatcher>

Throws:

StaticIllegalStateException - when this Signal has already been started.

See Also:

stop()

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this Signal, i.e., changes to a running state. A running signal is a source of activation when in a scoped memory and is a member of the root set when in the heap. A running signal can be triggered.

Specified by:

start in interface ActiveEvent<Signal,SignalDispatcher>

Throws:

StaticIllegalStateException - when this Signal has already been started.

Parameters:

disabled - true for starting in a disabled state.

See Also:

stop()

stop

public boolean stop()
             throws StaticIllegalStateException

Stops this Signal. A stopped signal ceases to be a source of activation and no longer causes any AE attached to it to be a source of activation.

Specified by:

stop in interface ActiveEvent<Signal,SignalDispatcher>

Throws:

StaticIllegalStateException - when this Signal is not running.

Returns:

true when this was enabled and false otherwise.

addHandler

public void addHandler(AsyncBaseEventHandler handler)

Description copied from class: AsyncBaseEvent

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

Overrides:

addHandler in class AsyncBaseEvent

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

setHandler

public void setHandler(AsyncBaseEventHandler handler)

Description copied from class: AsyncBaseEvent

Associate a new handler with this event and remove all existing handlers.

Overrides:

setHandler in class AsyncBaseEvent

Parameters:

handler - The instance of AsyncBaseEventHandler to be associated with this. When handler is null then no handler will be associated with this, i.e., behave effectively as if setHandler(null) invokes removeHandler(AsyncBaseEventHandler) for each associated handler.

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

Description copied from class: AsyncBaseEvent

Remove a handler from the set associated with this event. A removed handler continues to execute until its fireCount becomes a zero and it completes. When handler has a scoped non-default initial memory area and execution of this method causes handler to become unfirable this method shall not return until all related finalization has completed

Overrides:

removeHandler in class AsyncBaseEvent

Parameters:

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

send

public void send(long pid)
          throws POSIXSignalPermissionException,
                 POSIXInvalidTargetException

Sends this signal to another process.

On POSIX systems running in user space, the following holds:

• when pid is positive, the signal is sent to pid;
• when pid equals 0, the signal is sent to every process in the process group of the current process;
• when pid equals -1, the signal is sent to every process for which the calling process has permission to send signals, except for possibly OS-defined system processes; otherwise
• when pid is less than -1, the signal is sent to every process in the process group -pid.

POSIX.1-2001 requires the underlying mechanism of signal.send(-1) to send signal to all processes for which the current process may signal, except possibly for some OS-defined system processes.

For an RTVM running in kernel space, the meaning of the pid is implementation dependent, though it should be as closed to the standard definition as possible.

Throws:

POSIXSignalPermissionException - when the process does not have permission to send the target.

POSIXInvalidTargetException - when the target does not exist.

Parameters:

pid - The identifier of the process to which to send the signal.