javax.realtime.posix

Class RealtimeSignal

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncLongEvent

javax.realtime.posix.RealtimeSignal

All Implemented Interfaces:

ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>, Releasable<RealtimeSignal,RealtimeSignalDispatcher>

public final class RealtimeSignal
extends AsyncLongEvent
implements ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>

An ActiveEvent subclass for defining a POSIX realtime 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 RealtimeSignal	get(int id) Gets a POSIX realtime signal by its ID.
static RealtimeSignal	get(String name) Gets a POSIX realtime signal by its name.
RealtimeSignalDispatcher	getDispatcher() Obtain the current dispatcher for this event.
int	getId() Gets the ID of this realtime signal.
static int	getId(String name) Gets the ID of a supported POSIX realtime signal by its name.
static int	getMaxId() Determines the highest system id for realtime signals.
static int	getMinId() Determines the lowest system id for realtime signals.
String	getName() Gets the name of this signal.
boolean	isActive() Determines the activation state of this signal, i.e., whether or not it has been started.
static boolean	isRealtimeSignal(int id) Determines whether or not the given id represents a realtime signal.
static boolean	isRealtimeSignal(String name) Determines whether or not the given name represents a POSIX realtime signal.
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.
boolean	send(long pid, long payload) Sends this signal to another process.
RealtimeSignalDispatcher	setDispatcher(RealtimeSignalDispatcher 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 RealtimeSignal, i.e., changes to a running state.
void	start(boolean disabled) Starts this RealtimeSignal, i.e., changes to a running state.
boolean	stop() Stops this RealtimeSignal.
String	toString() Returns a string representation of the object.
void	trigger(long payload)

Methods inherited from class javax.realtime.AsyncLongEvent

fire

Methods inherited from class javax.realtime.AsyncBaseEvent

createReleaseParameters, disable, enable, finalize, handledBy, hasHandlers

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

Method Detail

isRealtimeSignal

public static boolean isRealtimeSignal(String name)

Determines whether or not the given name represents a POSIX realtime signal.

Parameters:

name - The name of the signal check.

Returns:

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

isRealtimeSignal

public static boolean isRealtimeSignal(int id)

Determines whether or not the given id represents a realtime signal.

Parameters:

id - The numerical signal identifier to check.

Returns:

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

getId

public static int getId(String name)
                 throws POSIXInvalidSignalException

Gets the ID of a supported POSIX realtime 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 whose ID should be determined.

Returns:

the ID of the signal named by name.

get

public static RealtimeSignal get(String name)
                          throws POSIXInvalidSignalException

Gets a POSIX realtime 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 to get.

Returns:

the realtime signal with name.

get

public static RealtimeSignal get(int id)
                          throws POSIXInvalidSignalException

Gets a POSIX realtime signal by its ID.

Throws:

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

Parameters:

id - The identifier of a POSIX realtime signal.

Returns:

the realtime signal corresponding to ID or null when no signal with that ID exists.

getMinId

public static int getMinId()

Determines the lowest system id for realtime signals.

Returns:

the equivalent of getId(String) called with the string "SIGRTMIN" or "SIGRT0".

getMaxId

public static int getMaxId()

Determines the highest system id for realtime signals.

Returns:

the equivalent of getId(String) called with the string "SIGRTMAX".

trigger

public void trigger(long payload)

getId

public int getId()

Gets the ID of this realtime signal.

Returns:

the ID of this signal.

getName

public String getName()

Gets the name of this signal.

Returns:

the name of this signal.

getDispatcher

public RealtimeSignalDispatcher getDispatcher()

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>

Specified by:

getDispatcher in interface Releasable<RealtimeSignal,RealtimeSignalDispatcher>

Returns:

the dispatcher associated with this event.

setDispatcher

public RealtimeSignalDispatcher setDispatcher(RealtimeSignalDispatcher value)

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

Specified by:

setDispatcher in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>

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<RealtimeSignal,RealtimeSignalDispatcher>

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<RealtimeSignal,RealtimeSignalDispatcher>

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 final void start()
                 throws StaticIllegalStateException

Starts this RealtimeSignal, i.e., changes to a running state. A running realtime 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 realtime signal can be triggered.

Specified by:

start in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>

Throws:

StaticIllegalStateException - when this RealtimeSignal has already been started.

See Also:

stop()

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this RealtimeSignal, i.e., changes to a running state. A running realtime 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 realtime signal can be triggered.

Specified by:

start in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>

Throws:

StaticIllegalStateException - when this RealtimeSignal has already been started.

Parameters:

disabled - true for starting in a disabled state.

See Also:

stop()

stop

public boolean stop()
             throws StaticIllegalStateException

Stops this RealtimeSignal. A stopped realtime 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<RealtimeSignal,RealtimeSignalDispatcher>

Throws:

StaticIllegalStateException - when this RealtimeSignal 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 boolean send(long pid,
                    long payload)
             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.

payload - The long value associated with a fire.

Returns:

true when successful and false when not due to a buffer overflow