Error Handling

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.