[glob2-devel] Error handling and reporting

[Andrew Sayers]

The next big bit of architecture I'm playing with is the error handling
and reporting mechanism.  At present, Glob2 does all its error handling
through the assert() macro, and reports messages by sending them
straight to standard error (i.e. to the console).

I'd never heard of assert() before I started working on Glob2, so I
thought I'd explain a bit about it.  It's called like this:

        assert(invariant)

where "invariant" is a test that should always return true.  Here's an
actual example of a failed assertion:

        glob2: Map.cpp:4167: void Map::updateForbiddenGradient(int, bool): 
Assertion `gradient' failed.

In other words, the assertion "gradient" failed in the function "void
Map::updateForbiddenGradient(int, bool)", in Map.cpp line 4167.
Examination of that line shows that the "gradient" is a pointer, so the
function must have been passed a null pointer.

The idea behind invariants is to explicitly test the assumptions behind
the algorithms you're writing (for example, that less than 20 units are
being asked to do a given job).  This is a useful debugging test, and
makes it easier for other people to read your code.  Assertions aren't
supposed to occur in production code, so defining the macro "NDEBUG"
causes assert()s to be ignored by the compiler.

Assertions and standard error messages are extremely useful as far as
they go, but have a lot of limitations:

* Assertions don't provide any information about why a test failed.
  For example, I would like "assert(myValue <= maxValue)" to tell me the
  value of myValue when it fails.
* They can only be turned on and off globally.  A lot of potentially
  useful debugging output gets commented out because it would
  create noise, and a lot of noise is emitted in case it's useful.
* They assume players look at the standard error.  Since Glob2 is still
  in the alpha stage, assertions etc. are (rightly) left in the code
  people play.  Unless the program is run from the command-line, errors
  and assertions are simply ignored - and when the game fails, players
  are treated to the very jarring experience of the game just vanishing.
* They can't easily be extended - for example, it would be extremely
  useful to save the current game, along with some debugging
  information, when an assertion fails.  Players could then send us that
  file in a bug report.
* They should only be used for debugging, but there's a strong
  temptation to use them for other things (like testing and reporting
  errors that should actually be possible)


I don't have a concrete suggestion for how I'd like error handling to
work yet, but I think some design goals for the system should be:

* There should be a single mechanism that can redirect error messages to
  the console, a log file, a message box, or can throw them away
* A way of handling assertions that discourages everyday use, a
  framework for creating more interesting classes of error, and a way of
  handling those interesting errors better (e.g. a network error saves
  the current game and exits to the end-game screen).
* Reporting should provide enough information for people trying to fix
  problems, without being threatening to users.
* Able to support "verbose" and "quiet" modes of normal running.  I
  think Glob2 might already have something like this, but I'm not sure
  how it works.  If it does, it should be incorporated into the new API.
* configurable on a per-class basis.  Each class should be able to
  configure debugging levels independently.  Classes should be able to
  have several debugging "profiles" - for example, one profile for
  impossible errors, another for ordinary complaints to the user.
* Fits in with C++'s exception-handling mechanisms, so that exceptions
  can be trapped, and appropriate action taken (e.g. saving the game
  before quitting).  This would also mean that it needs to avoid
  recursive loops of exceptions.

Does anyone have any other suggestions about design goals?  I've been
thinking over implementations for days and haven't found anything I like
yet.  Does anyone know of a project that's done this well, which we can
borrow ideas from?

        - Andrew