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. |
fire
createReleaseParameters, handledBy, hasHandlers
public 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()
ActiveEvent
getDispatcher
in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>
getDispatcher
in interface Releasable<RealtimeSignal,RealtimeSignalDispatcher>
public RealtimeSignalDispatcher setDispatcher(RealtimeSignalDispatcher dispatcher)
ActiveEvent
dispatcher
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 AsyncBaseEvent
true
when releasing, false
when skipping.public void enable()
AsyncBaseEvent
enable
in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>
enable
in class AsyncBaseEvent
public void disable()
AsyncBaseEvent
disable
in interface ActiveEvent<RealtimeSignal,RealtimeSignalDispatcher>
disable
in class AsyncBaseEvent
public 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 AsyncBaseEvent
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.public void setHandler(AsyncBaseEventHandler handler)
fire()
method.setHandler
in class AsyncBaseEvent
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.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 AsyncBaseEvent
handler
- The handler to be disassociated from this
. When
null
nothing happens.
When the handler
is not already associated with
this
then nothing happens.