Author: Stefan Eilemann
State: Design
Overview
This feature replaces the setErrorMessage used primarily during initialization with an error number and a global error number to string registry. It allows applications more easily to detect which operation has failed, and simplifies the error network transport.
Requirements
Provide integer error number and facilities for number-to-string conversion.
Design
Equalizer defines a set of error numbers starting at 0. A value is provided which is the minumum value defined by applications, which can define their own error numbers and should register an error string for this number.
Equalizer only transports the error number. The application is responsible for keeping the application-specific errors consistent across processes. Equalizer translates the error number to a string in log output, if a string for the error is registered.
Equalizer error strings are registered in each namespace's init function and removed in exit.
API
New functions:
void ComputeContext::setError( const uint32_t error );
Error ComputeContext::getError() const;
Error util::FrameBufferObject::getError() const;
// Attn affects all entities:
void fabric::Object::setError( const uint32_t error );
Error fabric::Object::getError() const;
static ErrorRegistry& base::Global::getErrorRegistry();
class ErrorRegistry
{
public:
const std::string& getString( const uint32_t error );
void setString( const uint32_t error, const std::string& text );
void eraseString( const uint32_t error );
private:
stde::hash_map< uint32_t, std::string > _errors;
};
namespace eq
{
namespace base
{
enum Error
{
ERROR_CUSTOM = EQ_64KB
};
}
namespace net
{
enum Error
{
ERROR_CUSTOM = base::ERROR_CUSTOM + EQ_64KB
};
}
enum Error
{
ERROR_WGL_TBD = net::ERROR_CUSTOM,
ERROR_AGL_TBD,
...
ERROR_CUSTOM = net::ERROR_CUSTOM + EQ_64KB
};
std::ostream& operator << ( std::ostream& os, const Error& error );
}
Removed functions:
void ComputeContext::setErrorMessage( const std::string& error );
const std::string& ComputeContext::getErrorMessage() const;
void SystemPipe::setErrorMessage( const std::string& error );
const std::string& SystemPipe::getErrorMessage() const;
const std::string& util::FrameBufferObject::getErrorMessage() const;
void fabric::Object::setErrorMessage( const std::string& error );
const std::string& fabric::Object::getErrorMessage() const;
File Format
No changes.
Restrictions
Error registration is not thread-safe.
Issues
Q1: Is error registration thread-safe?
Resolved: No.
Error registration typically happens once during application initialization. If thread-safety is required, an external mutex may be used.
Q2: Where is the error registry located?
Resolved: in the eq::base namespace.
While Equalizer currently uses errors only in the client initialization, error handling is a base functionality and we may later use it in the lower namespaces.
Each namespace will have it's own list of errors, which are built 'on top' of each other.
Q3: What about arguments used in the error string?
Resolved: The system error code or other information is not part of this feature.
Sometimes it is useful to include arguments, such as the system error code, in the error message. The system error can't be translated on another node, since it potentially uses another operating system.
Since most of the auxilary information is not strictly needed on the remote system it will not be transported. The local client creating the error will output detailed information and send a generic error code, which may refer to the client log.
