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) addHandler adds a handler to 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) removeHandler removes a handler from this event that was previously added by addHandler.
void	send(long pid) Sends this signal to another process or process group.
void	setHandler(AsyncBaseEventHandler handler) setHandler removes all handlers from the list of handlers for this event and adds the given handler.
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, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

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)

addHandler adds a handler to this event. If the handler has already been added, this is a nop.

Since a reference to handler has to be stored in this, an IllegalAssignmentError will be caused if handler is allocated in a memory area that does not permit to be stored in an object allocated in this' memory area.

This call will allocate a small object in the memory area this was allocated in.

The execution of addHandler is atomic with respect to removeHandler and fire.

ensures
(handler != null) ==> (handledBy(handler));

Overrides:

addHandler in class AsyncEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Parameters:

handler - the new handler.

setHandler

public void setHandler(AsyncBaseEventHandler handler)

setHandler removes all handlers from the list of handlers for this event and adds the given handler.

The execution of setHandler is atomic with respect to addHandler, removeHandler, handledBy, and fire.

ensures
((handler == null) || handledBy(handler));

Overrides:

setHandler in class AsyncEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Parameters:

handler - The handler to be added, null if none.

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

removeHandler removes a handler from this event that was previously added by addHandler.

The execution of removeHandler is atomic with respect to addHandler, setHandler, handledBy, and fire.

ensures
((handler == null) || !handledBy(handler));

Overrides:

removeHandler in class AsyncEvent

Throws:

UnsupportedOperationException - everytime, since this is not implemented yet.

Parameters:

handler - the handler to be removed. If this handler is null or has not been added to this event, nothing will happen.

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.