Cold Help System: Programming: ColdC Reference Manual: Implementation: Errors


When something goes wrong in a ColdC method an error is thrown. The interpreter will throw errors, and methods can throw custom errors (using the throw() function). An error consists of an error code (the type of error), a string describing the error, and--optionally--data relative to the error.

When the interpreter throws an error, it checks to see how the current method handles that error type. If the error occured in a critical expression (see Error-Handling Expressions), then the interpreter will cease evaluating the critical expression. Processing of the method will continue as if the interpreter had completed evaluation of the critical expression. The return value of the critical expression will be the error code associated with the thrown error. In this case, the traceback is not accessible from traceback(); in order to get a traceback, a catch statement must be used.

If the error did not occur in a critical expression, but occurred in a catch statement which catches the error code (either because it is a catch all statement or because it lists the error code (see Error-Handling Statements). Then the processing of the method jumps to the error handler, if one was provided, or to the end of the catch statement if not.

If the error did not occur in a critical expression or in an appropriate catch statement, then the current method aborts, and the interpreter throws an error in the calling method. Normally, the error thrown in the calling routine will have the error code ~methoderr unless the original error occurred within a propagation expression. If the error occurred within a propagation expression then the error code will be the same as it was for the original error. A propagation expression has no effect on how an error is handled except to cause the error code to propagate differently to the calling routine.

Errors are thrown using the throw() function. This does not throw an error in the current method; instead, it exits the current method and throws an error in the calling method. Thus a method cannot ignore an error which it threw itself using throw().

There is one case in which a method cannot catch an interpreter-generated error. Methods have a limited amount of time to run, measured in ticks. A method will generally only run out of ticks if it gets stuck in an infinite loop. If a method runs out of ticks, then the interpreter will throw a ~ticks error, which the method cannot catch. This causes the method to abort, which in turn causes the interpreter to throw a ~methoderr error in the calling routine.

Critical expressions should be used when calling code which is possibly buggy or when the method may be undefined, and it is undesirable for the current method to stop executing as a result. For instance, a method which announces a string to every object in a container should probably ignore errors in the methods for each individual object which handle receiving the string.

Catch statements should be used to handle errors in any way other than ignoring them. The catch statement is much more powerful than the critical expression, and is ideal for situations in which fine-grain control over error handling is required.

Propagation expressions should be used when the current method is an intermediary between an outside object and an internal feature. For instance, a method which checks permissions and calls an object function such as list_method() is acting as an intermediary. In this case, the method should throw the same errors as the list_method() function, so the function call should be enclosed within a propagation expression.


Methods | Tasks and Frames | Errors | Security | Networking | Regexps | Files


the Cold Dark