WiredTiger: Error handling

| Version 3.1.0

Fork me on GitHub Join my user group
Error handling

WiredTiger operations return a value of 0 on success and a non-zero value on error. Error codes may be either positive or negative: positive error codes are standard error codes as described for POSIX-like systems (for example, `EINVAL` or `EBUSY`), negative error codes are WiredTiger-specific (for example, `WT_ROLLBACK`).

WiredTiger-specific error codes always appear in the -31,800 to -31,999 range, inclusive.

WiredTiger returns `EBUSY` for operations requiring exclusive access, when an object is not available for exclusive access. For example, the WT_SESSION::drop or WT_SESSION::verify methods will fail if the object has open cursors. Note that internal WiredTiger threads may temporarily open cursors on objects (for example, threads performing operations like statistics logging), and operations may temporarily fail and return `EBUSY` when there are no application cursors open on the object.

The following is a complete list of the WiredTiger-specific return values:

WT_ROLLBACK
  This error is generated when an operation cannot be completed due to a conflict with concurrent operations. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.

WT_DUPLICATE_KEY
  This error is generated when the application attempts to insert a record with the same key as an existing record without the 'overwrite' configuration to WT_SESSION::open_cursor.

WT_ERROR
  This error is returned when an error is not covered by a specific error return.

WT_NOTFOUND
  This error indicates an operation did not find a value to return. This includes cursor search and other operations where no record matched the cursor's search key such as WT_CURSOR::update or WT_CURSOR::remove.

WT_PANIC
  This error indicates an underlying problem that requires a database restart. The application may exit immediately, no further WiredTiger calls are required (and further calls will themselves immediately fail).

WT_RUN_RECOVERY
  This error is generated when wiredtiger_open is configured to return an error if recovery is required to use the database.

WT_CACHE_FULL
  This error is only generated when wiredtiger_open is configured to run in-memory, and an insert or update operation requires more than the configured cache size to complete. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.

WT_PREPARE_CONFLICT
  This error is generated when the application attempts to update an already updated record which is in prepared state. An updated record will be in prepared state, when the transaction that performed the update is in prepared state.

# Translating errors

The WT_SESSION::strerror and wiredtiger_strerror functions return the standard text message associated with any WiredTiger, ISO C, or POSIX standard API.

const char *key = "non-existent key";
cursor->set_key(cursor, key);
if ((ret = cursor->remove(cursor)) != 0) {
fprintf(stderr,
"cursor.remove: %s\n",
cursor->session->strerror(cursor->session, ret));
return (ret);
}
const char *key = "non-existent key";
cursor->set_key(cursor, key);
if ((ret = cursor->remove(cursor)) != 0) {
fprintf(stderr,
"cursor.remove: %s\n", wiredtiger_strerror(ret));
return (ret);
}

Note that wiredtiger_strerror is not thread-safe.

# Message handling using the WT_EVENT_HANDLER

Specific error and other message handling can be configured by passing an implementation of WT_EVENT_HANDLER to wiredtiger_open or WT_CONNECTION::open_session.

For example, both informational and error messages might be passed to an application-specific logging function that added a timestamp and logged the message to a file, and error messages might additionally be output to the `stderr` file stream.

Additionally, applications will normally handle `WT_PANIC` as a special case. WiredTiger will always call the error handler callback with `WT_PANIC` in the case of a fatal error requiring database restart, however, WiredTiger cannot guarantee applications will see an application thread return `WT_PANIC` from a WiredTiger API call. For this reason, a correctly-written WiredTiger application will likely specify at least an error handler which will immediately exit or otherwise handle fatal errors. Note that no further WiredTiger calls are required after an error handler is called with `WT_PANIC` (and further calls will themselves immediately fail).

/*
* Create our own event handler structure to allow us to pass context through
* to event handler callbacks. For this to work the WiredTiger event handler
* must appear first in our custom event handler structure.
*/
typedef struct {
WT_EVENT_HANDLER h;
const char *app_id;
} CUSTOM_EVENT_HANDLER;
/*
* handle_wiredtiger_error --
* Function to handle error callbacks from WiredTiger.
*/
int
handle_wiredtiger_error(WT_EVENT_HANDLER *handler,
WT_SESSION *session, int error, const char *message)
{
CUSTOM_EVENT_HANDLER *custom_handler;
/* Cast the handler back to our custom handler. */
custom_handler = (CUSTOM_EVENT_HANDLER *)handler;
/* Report the error on the console. */
fprintf(stderr,
"app_id %s, thread context %p, error %d, message %s\n",
custom_handler->app_id, (void *)session, error, message);
/* Exit if the database has a fatal error. */
if (error == WT_PANIC)
exit (1);
return (0);
}
/*
* handle_wiredtiger_message --
* Function to handle message callbacks from WiredTiger.
*/
int
handle_wiredtiger_message(
WT_EVENT_HANDLER *handler, WT_SESSION *session, const char *message)
{
/* Cast the handler back to our custom handler. */
printf("app id %s, thread context %p, message %s\n",
((CUSTOM_EVENT_HANDLER *)handler)->app_id,
(void *)session, message);
return (0);
}
CUSTOM_EVENT_HANDLER event_handler;
event_handler.h.handle_error = handle_wiredtiger_error;
event_handler.h.handle_message = handle_wiredtiger_message;
/* Set handlers to NULL to use the default handler. */
event_handler.h.handle_progress = NULL;
event_handler.h.handle_close = NULL;
event_handler.app_id = "example_event_handler";
error_check(wiredtiger_open(home,
(WT_EVENT_HANDLER *)&event_handler, "create", &conn));