Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (S)
Guardian Procedure Calls Reference Manual—522629-013
14-151
SIGNALTIMEOUT Procedure
system time; it also varies slightly from processor to processor, because all the
processor clocks typically run at slightly different speeds. System time is
determined by taking the average of all the processor times in the system.
When measuring short intervals of time, the difference between processor time
and system time is negligible. However, when measuring long intervals of time
(such as several hours or more), the difference can be noticeable. For this reason,
it is not recommended that you make just one call to the SIGNALTIMEOUT
procedure to measure a long interval of time when you need a precise
measurement that is synchronized with system time. Instead, you should use a
sequence of two or more calls. (The same applies to other procedures, such as
DELAY, that also measure time by a processor clock.)
For example, if you want your application to be notified at a specific system time
after a long interval, you can use the SIGNALTIMEOUT procedure to set a timer to
expire shortly before the desired time. When the timer expires (that is, when a
timeout message is delivered to $RECEIVE), your application can compute the
remaining time and set another timer for the short interval that remains.
However, because the possibility of clock discrepancy becomes greater as the
interval being timed becomes longer, it would be even safer to measure a long
time interval by dividing it into a series of relatively short intervals. One method is
to compute the interval between the current time and the desired time and set a
timer to expire after half that interval. When the timer expires, compute the
remaining time and set another timer to expire after half that interval, and so on,
approaching the desired time by progressively smaller steps.
Message
•
Timeout message
When a time-list element (TLE) set by a call to the SIGNALTIMEOUT procedure
times out, a system message -22 (elapsed time timeout) is sent to the caller’s
$RECEIVE.
OSS Considerations
OSS processes can use this procedure and generate a system message. An OSS
signal is not generated.
Example
CALL SIGNALTIMEOUT( 1000D , , , TIMERTAG ); ! 10 seconds.
Note. Because a process must read $RECEIVE to be notified when a timer expires, there can
be a significant amount of delay before seeing the notification. For example, if a process is
waiting for an I/O operation to finish, or if a process has low priority and is waiting to execute, a
significant amount of time might pass before the process can read $RECEIVE. The
SIGNALTIMEOUT procedure should not be used in situations where such delays cannot be
tolerated.