Conditions are handled with a function called a handler . Handlers are established dynamically and have dynamic scope and extent. Thus, when a condition is signalled, the processor will call the dynamically closest handler. This can accept, resume or decline the condition (see with-handler for a full discussion and definition of this terminology). If it declines, then the next dynamically closest handler is called, and so on, until a handler accepts or resumes the condition. It is the first handler accepting the condition that is used and this may not necessarily be the most specific. Handlers are established by the special form with-handler.
The condition to be signalled.
The function to be called if the condition is handled and resumed, that is to say, the condition is continuable, or () otherwise.
If this argument is not supplied, the condition is signalled on the thread which called signal, otherwise, thread indicates the thread on which condition is to be signalled.
signal should never return. It is an error to call signal’s continuation.
Called to indicate that a specified condition has arisen during the execution of a program. If the third argument is not supplied, signal calls the dynamically closest handler with condition and continuation. If the second argument is a subclass of function, it is the resume continuation to be used in the case of a handler deciding to resume from a continuable condition. If the second argument is (), it indicates that the condition was signalled as a non-continuable condition—in this way the handler is informed of the signaler’s intention.
If the third argument is supplied, signal registers the specified condition to be signalled on thread. The condition must be an instance of the condition class <thread-condition>, otherwise an error is signalled (condition class: <wrong-condition-class>) on the thread calling signal. A signal on a determined thread has no effect on either the signalled or signalling thread except in the case of the above error.
thread-reschedule, thread-value, with-handler.
| call-next-handler-form: |
| ( call-next-handler ) |
The call-next-handler special form calls the next enclosing handler. It is an error to evaluate this form other than within an established handler function. The call-next-handler special form is normally used when a handler function does not know how to deal with the class of condition. However, it may also be used to combine handler function behaviour in a similar but orthogonal way to call-next-method (assuming a generic handler function).
The result of evaluating the handler function expression must be either a function or a generic function. This function will be called if a condition is signalled during the dynamic extent of protected-forms and there are no intervening handler functions which accept or resume the condition. A handler function takes two arguments: a condition, and a resume function/continuation. The condition is the condition object that was passed to signal as its first argument. The resume continuation is the continuation (or ()) that was given to signal as its second argument.
The sequence of forms whose execution is protected by the handler function specified above.
The value of the last form in the sequence of forms.
A with-handler form is evaluated in three steps:
The above is the normal behaviour of with-handler. The exceptional behaviour of with-handler happens when there is a call to signal during the evaluation of protected-form. signal calls the nearest closing handler-function passing on the first two arguments given to signal. The handler-function is executed in the dynamic extent of the call to signal. However, any signals occurring during the execution of handler-function are dealt withby the nearest enclosing handler outside the extent of the form which established handler-function. It is an error if there is no enclosing handler. In this circumstance the identified error is delivered to the configuration to be dealt with in an implementation-defined way. Errors arising in the dynamic extent of the handler function are signalled in the dynamic extent of the original signal but are handled in the enclosing dynamic extent of the handler.
There are three ways in which a handler-function can respond: actions:
An illustration of the use of all three cases is given here:
| Example 1: | handler actions |
the class of condition to be signalled.
a string containing relevant information.
a sequence of options to be passed to initialize-instance when making the instance of condition.
The result is ().
The error function signals a non-continuable error. It calls signal with an instance of a condition of condition-class initialized fromthe error-message, init-options and a resume continuation value of (), signifying that the condition was not signalled continuably.
the class of condition to be signalled.
a string containing relevant information.
a sequence of options to be passed to initialize-instance when making the instance of condition.
The result is ().
The cerror function signals a continuable error. It calls signal with an instance of a condition of condition-class initialized from the error-message, init-options and a resume continuation value which is the continuation of the cerror expression. A non-() resume continuation signifies that the condition has been signalled continuably.