AllegroPro Error Mechanism

Any AllegroPro component can produce errors. This API provides the ability for the user to detect the presence of an error and get information about the nature of that error.

Each thread will have a separate repository for errors. When a function results in an error condition, it calls the error mechanism and reports that an error occurred. Rather than using an obscure numbering system, the function creating the error is required to provide an error string that is sufficiently descriptive. This string is copied and stored by the thread's error repository, until requested by the user.

An error has a tag associated with it indicating severity. There are 3 levels of severity of errors. The lowest indicates an error that can be continued from with little regard for the consequences; the requested operation was simply not possible. The second level indicates an error that may leave one or more objects with corrupted, but functional, data. The third level leaves the object or driver in a non-functional state. These are fatal errors, and the program should terminate or abort when these arise.

The user can query whether or not an error has occurred, and get the error string that describes it, as well as the level of the error. This only operates on the errors for a particular thread; a thread may not query another threads errors.

The error repository will ignore subsequent errors as long as it has one error. The user may manually clear the error state for a thread as well.

Logging

The user can register an error logging function with the system. This function will be called any time an error occurs. This allows the user to pipe errors to any location they wish. Note that it is quite possible for these functions to run in a separate thread from the main thread. So the user should make certain to use semaphores to objects that both the main code and this function may wish to communicate with. The thread may also be a time-critical thread, so this code should do as little error processing as possible.

The user may filter error messages as well. This function should return whether or not the error in question should be posted to the given thread's error mechanism.

The user may specify that this callback be routed to an internal AllegroPro function that pipes errors into a specific log-file.