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) {                    \
    const char *msg;                                \
    int length;                                     \
    reme_context_get_last_error(c, &msg, &length);  \
      printf("Last error: %s", msg);                \
    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. For example, when all the initialization work has been done and scanning starts. The API provides you with methods such as reme_context_get_error_count, reme_context_get_first_error and reme_context_pop_first_error to determine the number of errors and to iterate over them.

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

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

  // Perform error checking at a critical point
  int nerrors = 0;  
  reme_context_get_error_count(c, &nerrors);

  for (int i = 0; i < nerrors; ++i) {
    const char *msg;
    int length;

    reme_context_get_first_error(c, &msg, &length);
    printf("%i : %s", msg);
    reme_context_pop_first_error(c);
  }

  // ...

  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.