Skip to main content

signal

signal Function

Syntax:

signal datum &rest arguments → nil

Arguments and Values:

datum, arguments—designators for a condition of default type simple-condition.

Description:

Signals the condition denoted by the given datum and arguments. If the condition is not handled, signal returns nil.

Examples:

(defun handle-division-conditions (condition) 
  (format t "Considering condition for division condition handling~%") 
  (when (and (typep condition ’arithmetic-error) 
	     (eq ’/ (arithmetic-error-operation condition))) 
    (invoke-debugger condition))) 
HANDLE-DIVISION-CONDITIONS 
(defun handle-other-arithmetic-errors (condition) 
  (format t "Considering condition for arithmetic condition handling~%") 
  (when (typep condition ’arithmetic-error) 
    (abort))) 
HANDLE-OTHER-ARITHMETIC-ERRORS 
(define-condition a-condition-with-no-handler (condition) ()) 
A-CONDITION-WITH-NO-HANDLER 
(signal ’a-condition-with-no-handler) 
NIL 
(handler-bind ((condition #’handle-division-conditions) 
	       (condition #’handle-other-arithmetic-errors)) 
  (signal ’a-condition-with-no-handler)) 
Considering condition for division condition handling 
Considering condition for arithmetic condition handling 
NIL 
(handler-bind ((arithmetic-error #’handle-division-conditions) 
	       (arithmetic-error #’handle-other-arithmetic-errors)) 
  (signal ’arithmetic-error :operation ’\* :operands ’(1.2 b))) 
Considering condition for division condition handling 
Considering condition for arithmetic condition handling 
Back to Lisp Toplevel

Side Effects:

The debugger might be entered due to *break-on-signals*.

Handlers for the condition being signaled might transfer control.

Affected By:

Existing handler bindings.

*break-on-signals*

See Also:

*break-on-signals*, error, simple-condition, Section 9.1.4 (Signaling and Handling Conditions)

Notes:

If (typep datum *break-on-signals*) yields true, the debugger is entered prior to beginning the signaling process. The continue restart can be used to continue with the signaling process. This is also true for all other functions and macros that should, might, or must signal conditions.

Expanded Reference: signal​

Basic Signaling​

signal signals a condition. If no handler handles it, signal returns nil rather than entering the debugger (unlike error).

(signal "Something happened")

=> NIL

Signaling a Custom Condition​

You can signal custom condition types. Handlers established via handler-bind or handler-case can intercept them.

(define-condition note (condition)
  ((text :initarg :text :reader note-text))
  (:report (lambda (c stream)
             (format stream "Note: ~A" (note-text c)))))

(handler-case
    (progn
      (signal 'note :text "Just an FYI")
      :normal-return)
  (note (c)
    (format nil "Handled: ~A" (note-text c))))

=> "Handled: Just an FYI"

Unhandled Signals Return NIL​

Unlike error, if no handler matches, execution continues normally.

(define-condition my-condition (condition) ())

(progn
  (signal 'my-condition)
  :continued)

=> :CONTINUED

Collecting Signaled Conditions with handler-bind​

Since handler-bind does not unwind the stack, you can observe a signal and let it pass through.

(let ((log '()))
  (handler-bind ((condition (lambda (c)
                              (push (format nil "~A" c) log))))
    (signal "event one")
    (signal "event two"))
  (nreverse log))

=> ("event one" "event two")

Difference Between signal and error​

signal is for conditions that may or may not be handled. error is for conditions that must be handled -- if not, it enters the debugger. This makes signal suitable for advisory or protocol-level conditions.

;; signal returns NIL when unhandled
(signal "advisory notice")

=> NIL
;; error would enter the debugger if unhandled
(handler-case (error "real problem")
  (error () :caught))

=> :CAUGHT