Error tracking

REDsdk uses a mechanism of error codes to report problems. Mainly there are two types of problems: misusages of the REDsdk API or errors from REDsdk itself. Both mechanisms are based on RED_RC returned values from most of the REDsdk API calls. A typical REDsdk API method uses several parameters and returns a RED_RC value.

REDsdk uses return codes for several reasons, among which the wish to not interfere with the hosting application exception policy: REDsdk won't trap system exceptions, segmentation faults or other low level signals that can be emitted on critical errors, letting the hosting application decide on the behavior to use.

Therefore it's critical to check all REDsdk functions and method return values to detect errors as soon as they arise.

Debug output

In addition to this, REDsdk features an error callback mechanism similar to a debug output system to gather extra informations on errors:

task

Task: Setup an error callback

An error callback can be set through the RED::IResourceManager interface:

// Access the resource manager:
RED::Object* resmgr = RED::Factory::CreateInstance( CID_REDResourceManager );
if( resmgr )
{
  RED::IResourceManager* iresmgr = resmgr->As< RED::IResourceManager >();
  RC_TEST( iresmgr->SetErrorCallback( MyErrorCallback, NULL ) );
}

Whenever an error gets raised by REDsdk, the callback gets called with all the available informations:

  1. The return code identifying the error in the first place.
  2. The calling method or function; This will point to internal REDsdk method names, but this can still provide valuable informations, and this can be also very useful to transmit this information to the REDsdk support.
  3. A relevant object address. This can point to an internal REDsdk object, or to a user object address, which was involved in raising the error.
  4. An extra expression field, that can contain a string value with the failing expression (generally used for 3rd party API calls such as OpenGL).
  5. An extra information field that can help diagnosing the error source.
  6. Extra user data that can be setup using RED::IResourceManager::SetErrorCallback.

In addition to this, it's possible to gather a text file that dumps all errors produced by REDsdk. For this simply create a 'redsdk_error.txt' file in the current folder of the application. This file will concatenate all errors produced by REDsdk. This file will be filled with all error informations, regardless of the existence of an error callback or not being set in the application.

Please note that if repeated errors arise (for instance a non critical error that happens every rendered frame), the size of the 'redsdk_error.txt' file may grow up quickly. So please don't forget to remove this file once the problem has been diagnosed.

The folder in which the "redsdk_error.txt" file is written to can be setup using RED::IResourceManager::SetErrorFilePath.