Event callbacks (and error handling in general)

Any parameter labelled event-cb is what’s known as an “event callback.” Event callbacks have one argument: a condition describing the event that caused them to be invoked. Originally event callbacks were failure callbacks, but since non-failure conditions are sometimes useful to an app, it made sense to make it more generic.

Application error handling

cl-async can be set up to catch errors in your application and pass them to your event-cb. This makes for seamless error handling, and keeps a rogue condition from exiting the event loop (assuming you have an event-cb set for the operation that generated the condition, or a default event handler that deals with the condition).

Note that the following variables are also controllable on a per-event-loop basis via the start-event-loop keyword arguments :catch-app-errors and :default-event-cb. It might actually be favorable to use start-event-loop since it creates thread-local versions of these variables when instantiating, which can be useful if running event loops in multiple threads.

*catch-application-errors*

default: nil

By setting this to true, you allow cl-async to catch conditions in your app and pass them to the event callback associated with the procedure that triggered the condition.

If this is left as nil, triggered conditions will make their way to the top level and cause the event loop to exit, cancelling any pending events (unless you have restarts implemented in your app).

*default-event-handler*

When *catch-application-errors* is set to t and an event-cb is not specified for an operation, the function assigned to this variable will be used as the event-cb. The default:

(lambda (ev)
  ;; throw the event so we can wrap it in a handler-case
  (handler-case (error ev)
    ;; got a connection error, throw it (must do this explicitely since
    ;; event-error extends event-info)
    (event-error () (error ev))

    ;; this is just info, let it slide
    (event-info () nil)))

This can be changed by your application if different behavior is desired.