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(java.lang.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(java.lang.String name) Gets the ID of a supported signal by its name.
java.lang.String	getName() Gets the name of this signal.
static long	getProcessId() Obtains the OS Id of the JVM process.
int	hashCode()
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(java.lang.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.
java.lang.String	toString()
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(java.lang.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(java.lang.String name)

Gets the ID of a supported signal by its name.

Parameters:

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

Returns:

the ID of the signal named by name.

Throws:

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

get

public static Signal get(java.lang.String name)

Gets a supported signal by its name.

Parameters:

name - The name identifying the signal to get.

Returns:

the registered signal associated with name or null.

Throws:

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

get

public static Signal get(int id)

Gets a supported signal by its ID.

Parameters:

id - The identifier of a registered signal.

Returns:

the signal corresponding to ID or null.

Throws:

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

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()

Overrides:

hashCode in class java.lang.Object

getName

public java.lang.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 java.lang.String toString()

Overrides:

toString in class java.lang.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>

Parameters:

disabled - true for starting in a disabled state.

Throws:

StaticIllegalStateException - when this Signal has already been started.

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>

Returns:

true when this was enabled and false otherwise.

Throws:

StaticIllegalStateException - when this Signal is not running.

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.

Parameters:

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

Throws:

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

POSIXInvalidTargetException - when the target does not exist.