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>

An ActiveEvent subclass for defining a POSIX realtime signal. Signal is capable of handling a signal that come from other process as well as sending it to another process described by its process id. The name of all the supported signal begins with SIG, such as SIGTERM, SIGABRT, etc. The signal that is possible to send or handle are the one available on the system.

Here is an example of using of the class:

 class SendSignalToSelf
 {
   public static void main(String[] args)
     throws POSIXSignalPermissionException,
       POSIXInvalidTargetException,
       POSIXInvalidSignalException
   {
     Signal signal = Signal.get("SIGFPE");
     Runnable run = () -> { System.out.println("Signal handled!"); };
     signal.setHandler(new AsyncEventHandler(run));
     signal.start(); // register the signal
     signal.send(Signal.getProcessId()); // send the signal to this process
     signal.disable(); //disable the signal, to no longer executed the handler
     signal.send(Signal.getProcessId());
     // the signal to this process, it will be handle, but the handlers
     // will not be executed
     signal.stop(); // deregister the signal
   }
 }

In the following, ID is used as the system numeric value of the realtime signal, for example, in most POSIX systems, SIGHUP has the value of 1.

Here is the list of all handled signals, but depending of the running system, this set of usable signal may be smaller.

Signal Name	Description
SIGHUP	Hangup (POSIX).
SIGINT	Interrupt (ANSI).
SIGQUIT	Quit (POSIX).
SIGILL	Illegal instruction (ANSI).
SIGTRAP	Trace trap (POSIX), optional signal.
SIGABRT	Abort (ANSI).
SIGBUS	BUS error (4.2 BSD), optional signal.
SIGFPE	Floating point exception.
SIGKILL	Kill, unblockable (POSIX).
SIGUSR1	User-defined signal 1 (POSIX).
SIGSEGV	Segmentation violation (ANSI).
SIGUSR2	User-defined signal 2 (POSIX).
SIGPIPE	Broken pipe (POSIX)
SIGALRM	Alarm clock (POSIX).
SIGTERM	Termination (ANSI).
SIGSTKFLT	Stack fault.
SIGCHLD	Child status has changed (POSIX).
SIGCONT	Continue (POSIX), optional signal.
SIGSTOP	Stop, unblockable (POSIX), optional signal.
SIGTSTP	Keyboard stop (POSIX), optional signal.
SIGTTIN	Background read from tty (POSIX), optional signal.
SIGTTOU	Background write to tty (POSIX), optional signal.
SIGURG	Urgent condition on socket (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGXCPU	CPU limit exceeded (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGXFSZ	File size limit exceeded (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGVTALRM	Virtual alarm clock (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGPROF	Profiling alarm clock (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGWINCH	Window size change (4.3 BSD, Sun). Not part of POSIX 9945-1-1996 standard.
SIGIO	I/O now possible (4.2 BSD). Not part of POSIX 9945-1-1996 standard.
SIGPWR	Power failure restart (System V). Not part of POSIX 9945-1-1996 standard.
SIGSYS	Bad system call, optional signal.
SIGIOT	IOT instruction (4.2 BSD), optional signal, same as SIGABRT.
SIGPOLL	Pollable event occurred (System V), same as SIGIO. Not part of POSIX 9945-1-1996 standard.
SIGCLD	Same as SIGCHLD (System V), optional signal.
SIGEMT	Not part of POSIX 9945-1-1996 standard.
SIGLOST	Not part of POSIX 9945-1-1996 standard.
SIGCANCEL	Not part of POSIX 9945-1-1996 standard.
SIGFREEZE	Not part of POSIX 9945-1-1996 standard.
SIGLWP	Not part of POSIX 9945-1-1996 standard.
SIGTHAW	Not part of POSIX 9945-1-1996 standard.
SIGWAITING	Not part of POSIX 9945-1-1996 standard.
SIGUNUSED	Since glibc 2.26, not defined, same as SIGSYS.
SIGINFO	A synonym for SIGPWR.

Since it is possible that several signal name have the same numerical id, the notion of preferred signal is provided. When several available signal names refers to the same number, the system chooses the name to give to the number as the name that comes first in the list above among all the synonyms. Thus, the method get(int) will returned the preferred name for the signal, even if several signals are available with the same number. A call to the method get(String) could also return a Signal whose name is not the name given as parameter, but the preferred name instead.

This class requires the following permissions:

Method	POSIXPermission Action
addHandler(javax.realtime.AsyncBaseEventHandler)	handle
addHandler(javax.realtime.AsyncBaseEventHandler)	handle, override
removeHandler(javax.realtime.AsyncBaseEventHandler)	override
send(long)	send
start()	control
stop()	control

Since:

RTSJ 2.0

See Also:

RealtimeSignal, SignalDispatcher, POSIXPermission

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Adds a handler to the set of handlers associated with this event.
void	disable() Changes the state of the event so that associated handlers are skipped on fire.
void	enable() Changes 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(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.
boolean	isActive() Determines the activation state of this signal, i.e., whether or not it is registered with a dispatcher.
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 the given name represents a POSIX signal.
void	removeHandler(AsyncBaseEventHandler handler) Removes a handler from the set associated with this event.
void	send(long pid) Sends this signal to another process or process group.
SignalDispatcher	setDispatcher(SignalDispatcher dispatcher) Change the current dispatcher for this event.
void	setHandler(AsyncBaseEventHandler handler) Associates a new handler with this event and removes all existing handlers.
void	start() Starts this Signal in the enabled state, i.e., changes its state to running: active and enabled.
void	start(boolean disabled) Starts this Signal, i.e., changes to an active state.
boolean	stop() Stops this Signal.

Methods inherited from class javax.realtime.AsyncEvent

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

Methods inherited from class javax.realtime.AsyncBaseEvent

createReleaseParameters, handledBy, hasHandlers

Methods inherited from class java.lang.Object

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

Method Detail

isSignal

public static boolean isSignal(java.lang.String name)

Determines if the given name represents a POSIX signal.

Parameters:

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

Returns:

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

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)
                 throws POSIXInvalidSignalException

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)
                  throws POSIXInvalidSignalException

Gets a supported signal by its name.

Parameters:

name - The name identifying the signal to get.

Returns:

the signal associated with name.

Throws:

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

get

public static Signal get(int id)
                  throws POSIXInvalidSignalException

Gets a supported signal by its ID.

Parameters:

id - The identifier of a registered signal.

Returns:

the signal corresponding to id or null when no signal with the given id exists.

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 the send(long) and RealtimeSignal.send(long, long) methods.

Returns:

the OS process ID.

getId

public int getId()

Gets the number of this signal.

Returns:

the signal number.

getName

public java.lang.String getName()

Gets the name of this signal.

Returns:

the name of this signal.

getDispatcher

public SignalDispatcher getDispatcher()

Description copied from interface: ActiveEvent

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 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<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 is registered with a dispatcher.

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.

enable

public void enable()

Description copied from class: AsyncBaseEvent

Changes 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

disable

public void disable()

Description copied from class: AsyncBaseEvent

Changes the state of the event so that 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

start

public void start()
           throws StaticIllegalStateException

Starts this Signal in the enabled state, i.e., changes its state to running: active and enabled. An active signal is a source of activation for its memory area and is a member of the root set when in the heap. A running signal can be triggered. Entering the active state causes it to be registered with its dispatcher.

Specified by:

start in interface ActiveEvent<Signal,SignalDispatcher>

Throws:

StaticIllegalStateException - when this Signal is active.

See Also:

stop()

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this Signal, i.e., changes to an active state. An active signal is a source of activation when in a scoped memory and is a member of the root set when in the heap. When called with disabled equal to false, it will also be running. An active signal can be triggered, but it must be running to dispatch its handlers.

Specified by:

start in interface ActiveEvent<Signal,SignalDispatcher>

Parameters:

disabled - true for starting in a disabled state.

Throws:

StaticIllegalStateException - when this Signal is active.

See Also:

stop()

stop

public boolean stop()
             throws StaticIllegalStateException

Stops this Signal. A stopped signal, i.e., inactive signal, ceases to be a source of activation and no longer causes any ActiveEvent attached to it to be a source of activation. This causes it to be deregistered from its dispatcher.

Specified by:

stop in interface ActiveEvent<Signal,SignalDispatcher>

Returns:

true when this was enabled and false otherwise.

Throws:

StaticIllegalStateException - when this Signal is inactive.

send

public void send(long pid)
          throws 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.

Parameters:

pid - ID 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.

addHandler

public void addHandler(AsyncBaseEventHandler handler)

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

Associates a new handler with this event and removes all existing handlers. The execution of this method is atomic with respect to the execution of the fire() method.

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., it behaves effectively as if setHandler(null) invokes AsyncBaseEvent.removeHandler(AsyncBaseEventHandler) for each associated handler.

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

Removes a handler from the set associated with this event. The execution of this method is atomic with respect to the execution of the fire() method.

A removed handler continues to execute until its fireCount becomes 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.