Overview EiffelMedia has an error handler class which can be accessed by inheriting from EM_SHARED_ERROR_HANDLER. You then get access to the Error_handler object.
When to use Error Handling
Whenever you have a feature which can fail you have to think about what to do on failure. You have multiple choices on how to react to a failure in such a moment. And which type of error handling depends on the kind of failure:
Ignoring
Just ignore the failure and go on . It is recommended to show at least a warning which does not hinder program flow but indicates that something happend.
- When
Do this when the failure is very unlikely and the client is not going to check for success on such an operation anyway. Also an error where neither the library nor the client can do anything about it can be ignored.
- Example
Drawing commands of a surface
can fail but no client is going to check after each draw if it was successful since such errors hardly ever occur. It is also unclear how to handle such a failure since it happend in SDL and the library has no clue what really happend. Also the client is not hindered when a drawing command is not succesfull - although the program may not look the same as if it worked. Thus when such an error occurs a warning is sufficent.
Status Report
Set a flag to indicate if an operation was successful.
- When
This is the recommended way of telling the client if an error occured.
- Example
When you open a UDP socket
there is a chance the port is alredy taken. This cannot be checked before and thus has to be tried. But since open doesn't ensure success the client can not rely on it and has to check afterwards using is_open.
Note: Since open doesn't ensure success no exception should be raised in case of failure
Raise Exception
Raise a developer exception.
- When
An exception has always to be thrown when a feature is going to break its contract - and only then! This indicates that the library can not work correctly anymore and the client has to decide if and how he handles it.
- Example
Some status setting
features in EM_SURFACE ensure in the postcondition the new status. But if the status cannot be set we are going to break the postcondition. In such a case an exception must to be thrown.
Note: These functions are very unlikely to fail and thus no client will even consider rescuing such exceptions. Thus there is no remark in the comment.
How to use Error Handling
The error handler can either raise a warning or an exception
. Both will display a message in the console as well as in the error log, the latter will additionaly raise a developer exception.
Error Codes
Any error is identified by a unique error code, an integer constant. To access these constants use the EM_ERROR_CODES class or the Error_handler object.
If you need an additional error type, add a new name to the appropriate section. Make sure the constant associated with the error is unique. However do not use the unique keyword since in case of an error the code is displayed and thus should be traceable to the specific error name.
Error Messages
Each error code can be mapped on an error message. This is done in the EM_ERROR_MESSAGES class. The way to add new messages should be clear since there are a lot of messages alredy defined.
To help debug applications, all error messages can be equiped with placeholders which get replaced by error-specific data when an error occured and the message is displayed. The placeholders are of the form “{#}” where # denotes the index in the error data tuple. “{0}” is a special placeholder which gets replaced by the error code as an integer number.
Error Data
When an exception or a warning
is raised through the error handler you have the possibility to pass some error data along as a tuple. When raising an exception
or error, just pass a tuple with the error data additionaly to the error code. If no error data is provided pass an empty
tuple.
The error data will be inserted into the error message by using the feature out on the passed objects and putting the generated strings into the error message.