
# Error policies

This document describes some policies on error handling.
We try to verify every input argument to every function.
We generally encourage copious use of `SC_ASSERT`.

 * `SC_ASSERT`

   Primarily used for internal development, failure on these asserts
   indicates a likely internal bug that requires modification of the
   library code by the developers.  These checks are only performed in
   debug mode.  It is highly recommended to `configure --enable-debug`
   except for times-critical production runs only.

   There can never be too many lines of `SC_ASSERT`.

 * `SC_ASSERT_VERBOSE` (does not yet exist...)

   Used for checks that do not depend on third party software, but are
   likely caused by improper use of the library by the user.  The verbose
   error message and likely failure cause should be transparent to the
   user, without knowledge of the library internals.  These checks are
   only performed in debug mode.

   Currently this is substituted for by `SC_ASSERT`.

 * `SC_CHECK_ABORT`

   Used when we are depending on third party software or file and network
   functions such as MPI.  Their consistency should always be checked.

   This macro is always enabled and intended to be used where the additional
   delay does not matter (say since file or network access takes some time
   already).

   Of course it would be preferable to report the error to the caller
   without provoking a crash.  But it is infinitely better than not
   checking at all.
