Signal handling

This section goes over how to tie into your operating system’s signaling system so your application can listen to the signals passed to it and act accordingly.

NOTE: Signal handling really only works on linux. It will run on windows, but don’t be surprised if your signals don’t catch.


(defun signal-handler (signo signal-cb &key event-cb))
  => nil

Create a signal handler. This listens for the given signo not only in the event loop, but also in the lisp app as well. It replaces the current lisp signal handler by calling C’s signal function. When a signal handler is freed via free-signal-handler, the original lisp signal handler is restored as it was before binding the signal handler.

Note that signals that aren’t freed via free-signal-handler or clear-signal-handlers will linger on even after all other events are out of the event loop, which prevents it from exiting. If you want your event loop to exit naturally, you must free your signals when you’re done with them.

;; example
(signal-handler 2 (lambda (sig) (format t "got SIGINT: ~a~%" sig))
                  (lambda (err) (foramt t "error processing signal callback: ~a~%" err)))

The signo arg is the POSIX integer signal you want to handle.

In the case of signal-handler, event-cb will only be called when an error occurs in the signal callback. There are no cl-async events that occur during signal processing.

signal-cb definition
(lambda (signo) ...)


(defun free-signal-handler (signo))
  => nil

Unbinds a signal handler. This deletes the underlying signal listener event and also restores the lisp signal handler that existed before calling signal-handler.

;; example
(signal-handler 2
  (lambda (sig)
    (close-server *my-app-server*)
    (free-signal-handler 2)))


(defun clear-signal-handlers ())
  => nil

Clear all cl-async bound signal handlers. This deletes the underlying event listeners and restores the original lisp signal handlers for each bound signal.

This is useful if you don’t want to track all the signals you’ve bound and free them manually, but don’t want to exit the event loop forcibly.

Signal definitions

These signals correspond directly to the unix signals:

  • +sighup+
  • +sigint+
  • +sigquit+
  • +sigill+
  • +sigtrap+
  • +sigabrt+
  • +sigemt+
  • +sigfpe+
  • +sigkill+
  • +sigbus+
  • +sigsegv+
  • +sigsys+
  • +sigpipe+
  • +sigalrm+
  • +sigterm+
  • +sigurg+
  • +sigstop+
  • +sigtstp+
  • +sigcont+
  • +sigchld+
  • +sigttin+
  • +sigttou+
  • +sigio+
  • +sigxcpu+
  • +sigxfsz+
  • +sigvtalrm+
  • +sigprof+
  • +sigwinch+
  • +siginfo+
  • +sigusr1+
  • +sigusr2+