default-error-handler-for-delivery

Arguments: project-or-app

This project property can be used to handle all unexpected errors that might be signaled in a delivered application that was generated from a project. The value of this property can be set on the Advanced tab of the Project Manager dialog, using the widget labeled Default Error Handler for Delivery.

The setf of this function may be called to set the value programmatically, though typically you would set the value interactively in the Default Error Handler for Delivery widget on the Advanced tab of the Project Manager dialog.

The value of this property should be the name of a function that accepts one argument, which will be the condition object for an error that was signaled. The default value is report-unexpected-error-and-exit, which displays a simple dialog about an unexpected error and then exits the application.

The function will be called whenever an otherwise unhandled error is signaled in the event-handling loop of an application that was generated from a project, if and only if the Enable Debugging of Runtime Errors option has been disabled on the Build tab of the Project Manager dialog (see ide:build-flags). The global variable *show-console-on-standalone-error* must also be true, as it is by default. If the function returns, event-loop will continue handling events.

To handle errors in a meaningful way, an application would typically use handler-case or handler-bind forms around small pieces of code in order to handle the particular errors that might be signaled in those places. But it may also be desirable to further trap all other unexpected errors, to allow the user to attempt to recover before exiting. Using this project property for that purpose is an alternative to wrapping general event handlers around all individual event-handling functions in a Common Graphics application, which could be very tedious.

As an example, a default error handler could call pop-up-message-dialog to report that an unexpected error has occurred, and give the user an option to let the program attempt to save their work before exiting. It could then do a save (perhaps after first doing a backup), and then call excl:exit to exit the application. The function alternately could return rather than calling excl:exit, to allow the user to continue working, though that's not recommended in this general case where the application is in an unpredictable state due to an unknown error. It could also exit the program by calling its own usual exit function (or call user-close on the main window, for example) rather than calling excl:exit, if the usual side effects are not too risky while in an unknown state.

In a generated application, this property will be on the cg:app object rather than on a project, since the project system does not exist in a generated application. An application could change this app property at runtime if desired; it exists on the app object in the IDE as well, though it is not used there.

If an error is signaled in an application's default-error-handler-for-delivery function itself, then Lisp will simply exit, and it may not be obvious why. In particular, that can happen if the error-handling code uses functionality from a Lisp module that exists in the IDE but not at runtime. To debug that, it may be necessary to artificially call the code that's in the error-handling function in a test version of the standalone app where Enable Debugging of Runtime Errors is turned on (see the Build tab of the Project Manager dialog).

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 8.2 release.
Created 2016.6.21.