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

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_NUM_SIGNALS Obtains the number of signals that can be processed.

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Add a handler to the set of handlers associated with this event.
void	disable() Change the state of the event so that the associated handlers are skipped on fire.
void	enable() Change the state of the event so that associated handlers are released on fire.
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() Obtains the dispatcher for this.
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.
boolean	isActive() Determines the activation state of this signal, i.e., whether or not it has been started.
static boolean	isPOSIXSignal(String name) Determines if a signal with a given name is registered.
boolean	isRunning() Determines the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.
void	removeHandler(AsyncBaseEventHandler handler) Remove a handler from the set associated with this event.
void	send(long pid) Sends this signal to another process or process group.
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.

Methods inherited from class javax.realtime.AsyncEvent

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

Methods inherited from class javax.realtime.AsyncBaseEvent

handledBy, hasHandlers

Methods inherited from class java.lang.Object

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

Field Detail

MAX_NUM_SIGNALS

public static final int MAX_NUM_SIGNALS

Obtains the number of signals that can be processed.

See Also:

Constant Field Values

Method Detail

isPOSIXSignal

public static boolean isPOSIXSignal(String name)

Determines if a signal with a given name is registered.

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Parameters:

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

Returns:

true when a signal with the given name is registered.

getId

public static int getId(String name)

Gets the ID of a supported signal by its name.

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

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:

UnsupportedOperationException - everytime, since this is not implemented yet.

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:

UnsupportedOperationException - everytime, since this is not implemented yet.

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

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

the OS process ID.

getId

public int getId()

Gets the number of this signal.

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

the signal number.

getName

public String getName()

Gets the name of this signal.

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

the name of this signal.

getDispatcher

public SignalDispatcher getDispatcher()

Obtains the dispatcher for this.

Specified by:

getDispatcher in interface Releasable<Signal,SignalDispatcher>

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

that dispatcher.

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>

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

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

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

true when releasing, false when skipping.

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.

UnsupportedOperationException - everytime, since this is not implemented yet.

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.

UnsupportedOperationException - everytime, since this is not implemented yet.

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.

UnsupportedOperationException - everytime, since this is not implemented yet.

Returns:

true when this was enabled and false otherwise.

send

public void send(long pid)
          throws POSIXInvalidSignalException,
                 POSIXSignalPermissionException,
                 POSIXInvalidTargetException

Sends this signal to another process or process group.

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:

POSIXInvalidSignalException - when the signal number is not valid.

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

POSIXInvalidTargetException - when the target does not exist.

UnsupportedOperationException - everytime, since this is not implemented yet.

Parameters:

pid - ID of the process to which to send the signal.

addHandler

public void addHandler(AsyncBaseEventHandler handler)

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

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

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)

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

Overrides:

setHandler in class AsyncBaseEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

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)

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

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

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

enable

public void enable()

Change the state of the event so that associated handlers are released on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method enables that request mechanism

Specified by:

enable in interface ActiveEvent<Signal,SignalDispatcher>

Overrides:

enable in class AsyncBaseEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

disable

public void disable()

Change the state of the event so that the associated handlers are skipped on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method disables that request mechanism

Specified by:

disable in interface ActiveEvent<Signal,SignalDispatcher>

Overrides:

disable in class AsyncBaseEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.