Event Handler Timeout Processing
The timeout processing information below, in combination with other event
handler guidelines, will help you develop event handlers that override or
extend standard model behavior. You can check timeout status using checkForTimeout.
When an event timeout expires, there are several possible processing states.
The most common states are:
- Event handler is executing
This means that the script
manager process has control of the client session to execute the logic
in the user's event handler. Host Integrator sends a timeout notification
that identifies the host session that has entered timeout processing. The
event handler code can also periodically check for this state by invoking
checkTimeout() on the callback interface.
In this state, most callback invocations result in an immediate return of
an EventTimeoutException. The callbacks that do not result in this exception
ScriptHostSession Interface: getCursorPosition, getRectangularTerminalRegion,
getLinearTerminalRegion, getTerminalScreenSize, getTerminalScreen, getStringAtCursor,
getStringAtOffset, getStringAtLocation, getPatternRegion, getPatternRegions,
getAttributeRegion, getAttributeRegions, getRecordSetRegion, getRecordRegion,
Event Interface:getLogger method for log level manipulation on the
Logger interface (isLogInfoEnabled, isLogWarningEnabled, logInfoMessage, logWarningMessage).
- Callback is executing
This occurs when the event handler makes a request to Host Integrator, and
that request is being processed when the timeout expires. In this case, the
same processing applies except that the callback return is a timeout error
that is converted into an EventTimeoutException in the script manager.
Additional error states
Once the timeout status has been communicated to the script manager, Host Integrator
begins another timer that governs how long the event handler is given to complete
and return control:
- If the event handler returns control within the time allotted, the errors
are reported to the client and the session remains intact.
- Abort mode: Should this new timer also expire,
Host Integrator enters into abort mode. Host Integrator returns an event handler
failure message to the invoking object (attribute, operation, etc.) and communicates
this new state to the script manager. The script manager "quarantines"
the event handler and its script manager session in a processing space separate
from normally functioning sessions and handlers. If this expired handler returns,
the response is ignored in favor of an AbortedSessionException in the standard
unhandled exception locations. Once the client has been notified of these
fatal errors, the host session is terminated and restarted. The Design Tool
always leaves the terminal intact and creates a single new session; the Session
Server will destroy the entire host session, including the virtual terminal,
and will only recreate it if a session pool minimum would not otherwise be
Abort mode may have some unpredictable side effects. Each abort results in
at least one quarantined thread in the script manager that could theoretically
exist for the life of the process. If the host session requires access to
the script manager to log out of the host properly, this can also fail with
unpredictable results for the host (for example, the host could lock the account
for a period time). It is strongly recommended, therefore, that event handlers
be written to conform to the timeout processing rules and that the handlers
check the timeout status periodically during tasks that could take significant
time to complete.
Timeout processing for nested events