Error Handling

How to perform basic error handling in ReconstructMe API

The ReconstructMe API is a pure C-based library. As such, it cannot make use of exceptions and exception handling, but must rely on transporting errors via error codes and similar instruments. Most the examples omit error handling for clearity. We catch up on this omission here.

Error codes

Every method in ReconstructMe API returns an error code of reme_error_t type. This enumeration type can be used to test the outcome of the last invocation. Here's a quick (and dirty) macro that simplifies this work.

// A simple macro that checks for any errors and exits if a method invocation failed.
#define OK(s)                                       \
  if (s != REME_ERROR_SUCCESS) {                    \
    reme_context_print_errors(c);                   \
    reme_context_destroy(&c);                       \
    exit(-1);                                       \
  }                                                 \
      

Using this macro, we can test each method for success and exit if one returns without success.

  // Create a new context
  reme_context_t c;
  OK(reme_context_create(&c));

  // Compile for OpenCL device using defaults
  OK(reme_context_compile(c));
  
  // Create a new volume
  reme_volume_t v;
  OK(reme_volume_create(c, &v));
  
  // ...

  reme_context_destroy(&c);

Note however that not all possible states of reme_error_t represent an error that should cause your application to shut-down. Take for example REME_ERROR_TRACK_LOST, it indicates that the last attempt to determine the sensor position from the current sensor data did not succeed. In this case you should would wait the next frame and try again, instead of closing your application.

Error Checking at Critical Points

Instead of checking the return code each time, you can test for errors only at critical points in your application and get detailed access to error messages. The API provides you with methods such as reme_context_bind_error_info that reflects the current error message state.

  // Create a new context
  reme_context_t c;
  reme_context_create(&c);

  // Compile for OpenCL device using defaults
  reme_context_compile(c);
    
  // ...

  // Access to all error messages is given through the generic options interface.
  // Once the options object is bound it always reflects the current errors state.
  reme_options_t errors;
  reme_options_create(c, &errors);
  reme_context_bind_error_info(c, errors);

  int nerrors;
  reme_options_get_repeated_count(c, errors, "messages", &nerrors);
  printf("Number of errors %i \n", nerrors);

  char msg[1024];
  for (int i = 0; i < nerrors; ++i) {    
    reme_options_get(c, errors, "messages", msg, 1024, i);
    printf("%i : %s \n", i, msg);
  }

  // A shortcut for the above code is to simply issue
  reme_context_print_errors(c);

  // In order reset any errors you can invoke clear on the options object
  reme_options_clear(c, errors);
  reme_context_print_errors(c); // Will give you zero errors

  // ...


  reme_context_destroy(&c);

Receiving Log Messages

ReconstructMe API supports logging callbacks to receive logging messages based on severity levels. Per reme_context_t one logging callback can be registered through the use of reme_context_set_log_callback. It allows you to pass a user_data parameter, that will be passed through to each invocation of the logging callback.

The callback looks like

// Logging callback
void on_error(reme_log_severity_t sev, const char *msg, void *user_data)
{
  switch (sev) {
    case REME_LOG_SEVERITY_INFO:
      {
        printf("INFO: %s\n", msg);
        break;
      }
    case REME_LOG_SEVERITY_WARNING:
      {
        printf("WARNING: %s\n", msg);
        break;
      }
    case REME_LOG_SEVERITY_ERROR:
      {
        printf("ERROR: %s\n", msg);
        break;
      }
  } 
}

To register your callback

  // Create a new context
  reme_context_t c;
  reme_context_create(&c);

  reme_context_set_log_callback(c, on_error, 0);

  // Compile for OpenCL device using defaults
  reme_context_compile(c);
    
  // ...

  reme_context_destroy(&c);

Note that the logging callback has to stay alive as long as the context exists, or a different callback is specified.