public final class RealtimeSignal extends AsyncLongEvent implements ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>
ActiveEvent subclass for defining a POSIX realtime
signal. A realtime signal, as defined in POSIX 1003.1b, is a signal
that may carry a numerical value with it and that have a special
queuing system to handle it. It is capable of handling a realtime
signal with its associated payload, as well as sending it to another
process described by its process id. The name formatting is SIGRT
followed by the number of the realtime signal to be used. For
example SIGRT0, or SIGRTMIN, for the first realtime
signal, SIGRT1 for the second and SIGRTMAX for the
last one.
Here is an example of using of the class:
class SendRealtimeSignalToSelf
{
public static void main(String[] args) throws POSIXInvalidSignalException
{
RealtimeSignal rs = RealtimeSignal.get("SIGRTMIN");
LongConsumer lc = (l) -> { System.out.println("The payload is " + l); };
rs.setHandler(new AsyncLongEventHandler(lc));
rs.start(); // register the signal
rs.send(Signal.getProcessId(), 420); // send the signal this process
rs.disable(); //disable the signal, so the handler no longer executes
rs.send(Signal.getProcessId(), 1997);
// the signal is sent to this process, it will be handled, but
// the handlers will not be executed
rs.stop(); // deregister the signal
}
}
The current state of the implementation of the POSIX mechanism on most
system does not enable guaranteeing that one can send or receive
realtime signal with payloads whose size is above 16 bits.
In the following, the system numeric value of the realtime signal is
referred to as ID. For example, in most POSIX systems,
SIGRTMIN's value is 34.
This class requires the following permissions:
| Method | POSIXPermission Action |
|---|---|
addHandler(javax.realtime.AsyncBaseEventHandler) |
handle |
setHandler(javax.realtime.AsyncBaseEventHandler) |
handle, override |
removeHandler(javax.realtime.AsyncBaseEventHandler) |
override |
send(long, long) |
send |
start() |
control |
stop() |
control |
Signal,
RealtimeSignalDispatcher| 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 RealtimeSignal |
get(int id)
Gets a POSIX realtime signal by its ID.
|
static RealtimeSignal |
get(java.lang.String name)
Gets a POSIX realtime signal by its name.
|
RealtimeSignalDispatcher |
getDispatcher()
Obtain the current dispatcher for this event.
|
int |
getId()
Gets the name of this realtime signal.
|
static int |
getId(java.lang.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.
|
java.lang.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(java.lang.String name)
Determines whether or not the given name represents a realtime
signal.
|
boolean |
isRunning()
Determines the firing state (releasing or skipping) of this signal,
i.e., whether or not is active and enabled.
|
void |
removeHandler(AsyncBaseEventHandler handler)
Removes a handler from the set associated with this event.
|
boolean |
send(long pid,
long payload)
Sends this signal to another process.
|
RealtimeSignalDispatcher |
setDispatcher(RealtimeSignalDispatcher 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
RealtimeSignal, i.e., changes to a running state:
active and enabled. |
void |
start(boolean disabled)
Starts this
RealtimeSignal, i.e., changes to an active state. |
boolean |
stop()
Stops this
RealtimeSignal, i.e., change its state to inactive. |
firecreateReleaseParameters, handledBy, hasHandlerspublic static boolean isRealtimeSignal(java.lang.String name)
name - The name of the signal check.true when a signal with the given name is defined, but
false in all other cases.public static boolean isRealtimeSignal(int id)
id - The numerical signal identifier to check.true when a signal with the given id is defined, but
false in all other cases.public static int getId(java.lang.String name)
throws POSIXInvalidSignalException
name - The name of the signal whose ID should be determined.name.POSIXInvalidSignalException - when no signal with the given
name exists or name is null.public static RealtimeSignal get(java.lang.String name) throws POSIXInvalidSignalException
name - The name of the signal to get.POSIXInvalidSignalException - when no signal with the given
name exists or name is null.public static RealtimeSignal get(int id) throws POSIXInvalidSignalException
id - The identifier of a POSIX realtime signal.null when
no signal with that ID exists.POSIXInvalidSignalException - when no signal with the given
identifier id exists.public static int getMinId()
getId(String) called with the string
"SIGRTMIN" or "SIGRT0".public static int getMaxId()
getId(String) called with the string
"SIGRTMAX".public int getId()
public final java.lang.String getName()
public RealtimeSignalDispatcher getDispatcher()
ActiveEventgetDispatcher in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>getDispatcher in interface Releasable<RealtimeSignal,RealtimeSignalDispatcher>public RealtimeSignalDispatcher setDispatcher(RealtimeSignalDispatcher dispatcher)
ActiveEventdispatcher is null, the default dispatcher is restored.setDispatcher in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>public boolean isActive()
isActive in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>true when active; false otherwise.public boolean isRunning()
isRunning in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>isRunning in class AsyncBaseEventtrue when releasing, false when skipping.public void enable()
AsyncBaseEventenable in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>enable in class AsyncBaseEventpublic void disable()
AsyncBaseEventdisable in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>disable in class AsyncBaseEventpublic final void start()
throws StaticIllegalStateException
RealtimeSignal, i.e., changes to a running state:
active and enabled. An active realtime signal is a source of activation
for its memory area and is a member of the root set when in the heap.
An active signal can be triggered, but it must be running to dispatch its
handlers.start in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>StaticIllegalStateException - when this
RealtimeSignal is active.stop()public final void start(boolean disabled)
throws StaticIllegalStateException
RealtimeSignal, i.e., changes to an active state.
An active realtime signal is a source of activation for its memory area
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.start in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>disabled - true for starting in a disabled state.StaticIllegalStateException - when this
RealtimeSignal is active.stop()public final boolean stop()
throws StaticIllegalStateException
RealtimeSignal, i.e., change its state to inactive.
A stopped realtime signal ceases to be a source of activation and no
longer causes any ActiveEvent attached to
it to be a source of activation.stop in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>true when this was
enabled; false otherwise.StaticIllegalStateException - when this
RealtimeSignal is inactive.public boolean send(long pid,
long payload)
throws POSIXSignalPermissionException,
POSIXInvalidTargetException
pid - The identifier of the process to which to send the signal.payload - The long value associated with a fire.true when successful and false when not
due to a buffer overflow.POSIXSignalPermissionException - when the process does not
have permission to send the target.POSIXInvalidTargetException - when the target does not exist.public void addHandler(AsyncBaseEventHandler handler)
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.
addHandler in class AsyncBaseEventhandler - 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.public void setHandler(AsyncBaseEventHandler handler)
fire() method.setHandler in class AsyncBaseEventhandler - 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.public void removeHandler(AsyncBaseEventHandler handler)
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.
removeHandler in class AsyncBaseEventhandler - The handler to be disassociated from this. When
null nothing happens.
When the handler is not already associated with
this then nothing happens.