Guardian Procedure Calls Reference Manual

param1
input
INT:value
identifies the timeout message read from $RECEIVE.
param2
input
INT(32):value
identifies the timeout message read from $RECEIVE (same purpose as param1).
tag
output
INT:ref:1
returns an identifier associated with the timer. This tag should be used only to call the
CANCELTIMEOUT procedure.
Condition Code Settings
indicates that SIGNALTIMEOUT is unable to allocate a time list element (TLE). This can occur if fewer
than one-fourth of the TLEs are free.
< (CCL)
indicates that SIGNALTIMEOUT completed successfully.= (CCE)
indicates that the given timeout value is invalid.> (CCG)
Considerations
• SIGNALTIMEOUT and CANCELTIMEOUT
A process can use the SIGNALTIMEOUT procedure with the CANCELTIMEOUT procedure to
verify that some programmatic operation finishes within a certain elapsed time. The process
calls SIGNALTIMEOUT before initiating the operation and then periodically reads $RECEIVE
to watch for timer expiration. The process calls CANCELTIMEOUT after completion of the
timed operation if the process has not been signaled on $RECEIVE.
• Measuring elapsed time that a process executes
SIGNALTIMEOUT measures elapsed time (according to the processor clock) that this process
executes. Elapsed time includes the time spent by the processor in process code, in system
code, processing interrupts that occur while the process is running, and any time that the
process is waiting.
• Using SIGNALTIMEOUT to measure long time intervals
SIGNALTIMEOUT measures time according to the internal clock of the processor in which the
calling process is executing. Typically, processor time (that is, time as measured by a particular
processor) is slightly different from 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 SIGNALTIMEOUT to measure a long interval of time when you need a precise
measurement that is synchronized with system time. Instead, 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 SIGNALTIMEOUT to set a timer to expire shortly before the desired time.
SIGNALTIMEOUT Procedure 1381