Error Handling

...

Problems

Clojure's rich, unified approach to data does not extend to exception types. As a result:

• error handling is interop, not awesome
  • built-in Java exception types provide one-off APIs
    • can't consume them as data interactively or programmatically
  • people in Clojure add to the mess by making more
  • exception handling still driven by fixed inheritance hierarchy
    • not idiomatic anywhere else in Clojure
• precompilation of code should not be necessary
  • projects dragged there just for exceptions
• information is not available when you need it to respond
  • interactive response: want data
    • maps not custom types
  • and more of it
    • locals
    • dynamics
    • the expression that caused the problem

Assumptions / Constraints

• but the information cannot cost a fortune
  • pay for what you need
  • dynamic selection of error handling features
  • requirement for wrapping not idiomatic in Clojure, and unacceptable
• Integrate well with platform
• Work ok (= no worse than Java) for interop callers
• Exceptions are not for flow control
  • multimethod dispatch speed probably ok
• Not trying to add conditions today
  • but don't want to make any choices that prohibit them later

Phase One

Provide built-in Clojure exception types that are richer than Java exceptions, and eliminate the need for app developers to gen-class their own exception types. Since some information is costly to provide, provide a *debug* flag that allows the costly stuff to be disabled in production.

Debug Builds

• the following group of features will be enabled when *debug* is set
  • assert
  • *unchecked-math* math becomes checked math
    • explicit unchecked does not change (might be for semantic reasons)
  • include locals (and bindings ??) in all thrown errors (or in assertions if this is too hard)
    • is conditional in throw path too expensive?
    • otherwise compile throw differently based on flag
• unify with Java assertions?
  • Not now. this can be done as a separate enhancement later
  • see discussion at http://dev.clojure.org/jira/browse/CLJ-250
• Need separate assert-like constructs that never get turned off
  • typical name: verify
  • for preconditions: prefix either verify- or assert- to :pre and :post ??
    • what is the default ??

Errors as Data

Provide built-in types than extend a few subclasses Throwable and also provide IPersistentMap. Goal: The new types are capable enough that Clojure programmers can be out of the business of making new Throwable subclasses.

• expose error info as part of the map
• clojure owns unnamespaced keywords
• include :namespace key
  • will be a great match target, alleviate one want for typed exceptions
• no need to include :fn key
  • not a good match target
  • available for human consumption in context of stacktrace
• need a few different types
  • error, runtimeexception, assertion?
• need names
  • unworkable: Clojure, PersistentMap,
  • maybe: Condition (but don't want to suggest non-error flow control)
• provide fn that parses Java exceptions into similar maps
  • e.g. clj-stacktrace
• REPL exception help works in terms of maps, not Java exceptions

• platform uses types for dispatch
  • only error handling is platform error handling
• want to carry data payloads
  • platform exceptions don't
• need out-of-band communication
  • for both ordinary and exceptional things!
    • exceptional things are ordinary during development
  • and ways to discover the oob mechanisms
• can't deal with exception at point it happens
  • can't resume
• cannot manipulate exceptions as data

Symptoms

• new application problems beget new types
  • types are heavy
  • why don’t people use an existing type?
    • want to branch on it (flow control)
    • habit
    • carry data
• new exception types lead to
  • gen-class (+ precompilation)
  • Java classes in Clojure projects
• use big things to solve small problems
  • condition library (e.g. Contrib Condition) when all you want is data
  • exceptions when all you want is control flow
    • idiomatic on many JVM languages
    • don't have composite returns or dynamic binding
• can't troubleshoot problems
  • info is gone when call stack unwinds

Example Use Cases

• communicate ordinary things
  • recover from I/O failure
  • convey detailed information for reporting in test framework
• communicate exceptional things
  • program bugs
  • platform and hardware failures
• jump to debugger based on situation
• add information to an exception
  • e.g. Alan's adorning macro arity example
• troubleshoot build failure that is only on Hudson

Constraints

• dispatch should be fast
  • where exceptions are used for exceptional things, performance is not an issue
• error handling should unify at bottom with Java
• neither ordinary nor exceptional things should have to pollute API for fns that don't care or can't respond
  • pay for what you need

An even-more modest proposal

I think we should implement

• education on dynamic bindings
• bindable *assertion-handler*
• (maybe) clj-stacktrace-like data-ification fns for exceptions
• (maybe) data-carrying *RuntimeException* subclass

All of these ideas, and several others not chosen, are documented below.

Some approaches

Table of some approaches and how they address the problems above. Approaches described in more detail below. Some of the approaches are deliberately crazy for contrast (wonder if we will agree on which ones).

Education on Dynamic Binding

Document dynamic binding as the Clojure Way to do out-of-band-control flow

• find likely place within Clojure or Contrib and implement examplar
• write docs and tutorial
• add "control flow" link from exception handling parts of Clojure docs

Clj-stacktrace

• define a standard vocabulary for data-izing the information in a clojure exception
• package in fns
  • do not call these fns automatically
  • maybe provide REPL helpers that do
• other parts of clj-stactkrace (color printing etc.) should remain tool features
• open questions
  • what do the REPL fns look like?
  • might start with the data and wait to see how they get used

Ad hoc conditions

E.g. Contrib condition or error-kit.

• could unify with Java exceptions, or not
• could include data-carrying exception, or not

Not carrying this idea forward at this point.

Pattern Matching Conditions

Pattern matching (a la Matchure), plus exceptions as data, plus dynamic binding.

Not carrying this idea forward at this point.

Data-carrying exception

Single exception type that can carry data, allowing clojure data tools to be used to process exceptions.

• subclass RuntimeException?
  • or one new type for each family (error, runtime, assertion?)
• unify keys with clj-stackrace or equivalent if that is also done
• open questions
  • what are the programmatic (non-interactive) uses of this data?

Enrich exceptions with local context

• add locals, bindings, kitchen sink to exceptions
• could be debug-only
• could be tied to throw, or only to assertions

Bindable test/assertion handler

• Create a bindable *assertion-handler* that can run with full context at the point an assertion fails
  • application of dynamic binding to the problem "Assertion fails where I can't get a debugger" (e.g. Hudson)
  • default behavior is to raise the error
  • facilitates use of assertion as the primary/only mechanism for tests, instead of separate fns like is
• implicitly debug-only through tie to assertions
  • once assertions are debug-only, anyway
• maybe assertions should never have been exceptions in the first place
  • more of a use case for handlers than for exceptions
  • unexpected errors are, ironically, expected errors during development
• making assertions handler-based solves my "assertions are backwards" rant
  • handler can do anything it needs to with local context
• also decouples the Java enablement issue
  • clojure binding controls initial reaction
  • Java -ea flag controls fallback behavior (assert or do nothing)
• open questions
  • encourage test frameworks to bottom out at assert, instead of their own ad-hoc things?
  • what does the fn take?
    • source code forms of the assertion
    • want access to locals
• very useful on CI
  • dump everything you know

Bindable throw handler

• like the assertion handler, but tied to all (Clojure) throws
• *throw-handler* should be available (in effect?) only under debug mode
  • pay for what you need
• open questions
  • what does the fn take?
    • source code forms
    • access to locals
    • args to exception
• very useful in CI
  • dump everything you know

Platform-based handler

Is there JVM support for automating handlers like the assert handler or throw handler? If these exist, and are flexible and easy to deploy, could use them instead of extending Clojure.

• not aware of any
• Clojure versions would work on other platforms

Bindable edge handler

• try to make all exceptions handle-able by wrapping clojure/java boundary everywhere
• when exception from Java land hits Clojure boundary, call the handler before propagating it
• attempt here is to respond closer to the problem
  • but halfway between the problem and the outer handler isn't much better than a full stack unwind
  • nothing special about the Clojure/Java boundary
• pervasive implementation and performance issues
• non-idiomatic wrapping
• ok, this is a crazy idea

Weaknesses of the modest proposal

• still no automatic way to discover relevant bindings
  • documentation, of course
  • but no programmatic way to discover relevant situation handlers
  • checked exceptions got this half-right
• Java/Clojure boundary visible on exceptions-as-data
  • Clojure exception can give you everything
  • with Java exception you have to ask by calling a fn
• Java/Clojure boundary visible on throw handler
  • no straigtforward way to sneak into Java
• if there is any commonality in how to write a bindable handler, it isn't captured here
• nothing stops an exception from being unnecessarily data-ized multiple times