Tech/LxEngine/Error Handling

Assertions
Reserved for catching programmer preventable conditions. This obviously is not a strict definition, as it is not possible for all such conditions to be foreseen in advance, and may instead result instead from unforeseen runtime conditions. s are not compiled into production code.

With the rare exception of very high-performance inner-loop code, asserts should be accompanied with production code for issuing and error or warning along with the assert.

Examples

 * Method/Function pre-conditions & post-conditions

Suggestions

 * Overuse rather than under-use asserts during development of new code. It is better to have to remove an assert for an unexpected, but possible condition than maintain incorrect expectations about
 * asserts are another form of documentation. Since there is not runtime penalty to production code, using asserts as a form of commentary on the expected behavior and data conditions is highly encouraged.

Fatal Errors
Reserved for non-recoverable errors where the application should save critical data, but otherwise shutdown as soon as possible. Will throw an lx::fatal_exception exception. During 'normal' operations, a fatal error should never occur.

An application should catch a lx::fatal_exception only to save any critical data then re-throw the exception to allow higher-level systems an opportunity to likewise save critical data.

Examples

 * Memory corruption detected
 * Unrecoverable internal data integrity corruption error
 * Unrecoverable out-of-memory or other hardware resource problems

Questions

 * What is the mechanism by which other threads are notified of a lx::fatal_exception?

Errors
Reserved for potentially recoverable error where the application should save critical data, but otherwise shutdown as soon as possible. Will throw an lx::error_exception exception.

An application may catch and consume an lx::error_exception, but should do so only with the error condition is fully understood to be correctable.

Examples

 * TBD

Warnings
Reserved for ignorable or locally recoverable conditions that indicate an inefficiency.

Log Messages
Reserved for messages logged in production code noting significant events that will be useful in reproducing or analyzing the before of a customer application instantiation.

Examples

 * Initialization & shutdown of a major subsystem
 * Initialization & shutdown of a plug-in
 * Any significant data save or check-pointing operation

Debug Messages
Reserved for debug-only messages that produce verbose output for in-development code. Due to the intentional verbosity, the debug messages are each associated with a channelId. Each channel is disabled by default, with the intention that a developer would enable only the channel or channels within which he or she is debugging or developing.

Examples

 * Minor events at too granular a level to belong as a  call
 * Basic statistics on the code being run

Suggestions

 * How to use   effectively is unfortunately difficult to generalize.  It requires a careful balance of providing detailed information about the subsystem or code area, but not so much data as to drown-out the most poignant data.
 * A useful strategy is to use  to display data that is difficult directly   against.  The programmer may be able to use to textual output of the debugging information to determine if a condition holds in a specific case where it could have been too difficult to assert in all cases.