Chapter 5. Error handling

typedef void igraph_error_handler_t (const char *reason, const char *file,
                                     int line, int igraph_errno);

This is the type of the error handler functions.

Arguments: 

IGRAPH_EXPORT igraph_error_handler_t igraph_error_handler_abort;

The default error handler, prints an error message and aborts the program.

IGRAPH_EXPORT igraph_error_handler_t igraph_error_handler_ignore;

This error handler frees the temporarily allocated memory and returns with the error code.

IGRAPH_EXPORT igraph_error_handler_t igraph_error_handler_printignore;

Frees temporarily allocated memory, prints an error message to the standard error and returns with the error code.

typedef enum {
    IGRAPH_SUCCESS           = 0,
    IGRAPH_FAILURE           = 1,
    IGRAPH_ENOMEM            = 2,
    IGRAPH_PARSEERROR        = 3,
    IGRAPH_EINVAL            = 4,
    IGRAPH_EXISTS            = 5,
    IGRAPH_EINVEVECTOR       = 6,
    IGRAPH_EINVVID           = 7,
    IGRAPH_NONSQUARE         = 8,
    IGRAPH_EINVMODE          = 9,
    IGRAPH_EFILE             = 10,
    IGRAPH_UNIMPLEMENTED     = 12,
    IGRAPH_INTERRUPTED       = 13,
    IGRAPH_DIVERGED          = 14,
    IGRAPH_ARPACK_PROD       = 15,
    IGRAPH_ARPACK_NPOS       = 16,
    IGRAPH_ARPACK_NEVNPOS    = 17,
    IGRAPH_ARPACK_NCVSMALL   = 18,
    IGRAPH_ARPACK_NONPOSI    = 19,
    IGRAPH_ARPACK_WHICHINV   = 20,
    IGRAPH_ARPACK_BMATINV    = 21,
    IGRAPH_ARPACK_WORKLSMALL = 22,
    IGRAPH_ARPACK_TRIDERR    = 23,
    IGRAPH_ARPACK_ZEROSTART  = 24,
    IGRAPH_ARPACK_MODEINV    = 25,
    IGRAPH_ARPACK_MODEBMAT   = 26,
    IGRAPH_ARPACK_ISHIFT     = 27,
    IGRAPH_ARPACK_NEVBE      = 28,
    IGRAPH_ARPACK_NOFACT     = 29,
    IGRAPH_ARPACK_FAILED     = 30,
    IGRAPH_ARPACK_HOWMNY     = 31,
    IGRAPH_ARPACK_HOWMNYS    = 32,
    IGRAPH_ARPACK_EVDIFF     = 33,
    IGRAPH_ARPACK_SHUR       = 34,
    IGRAPH_ARPACK_LAPACK     = 35,
    IGRAPH_ARPACK_UNKNOWN    = 36,
    IGRAPH_ENEGLOOP          = 37,
    IGRAPH_EINTERNAL         = 38,
    IGRAPH_ARPACK_MAXIT      = 39,
    IGRAPH_ARPACK_NOSHIFT    = 40,
    IGRAPH_ARPACK_REORDER    = 41,
    IGRAPH_EDIVZERO          = 42,
    IGRAPH_GLP_EBOUND        = 43,
    IGRAPH_GLP_EROOT         = 44,
    IGRAPH_GLP_ENOPFS        = 45,
    IGRAPH_GLP_ENODFS        = 46,
    IGRAPH_GLP_EFAIL         = 47,
    IGRAPH_GLP_EMIPGAP       = 48,
    IGRAPH_GLP_ETMLIM        = 49,
    IGRAPH_GLP_ESTOP         = 50,
    IGRAPH_EATTRIBUTES       = 51,
    IGRAPH_EATTRCOMBINE      = 52,
    IGRAPH_ELAPACK           = 53,
    IGRAPH_EDRL              = 54,
    IGRAPH_EOVERFLOW         = 55,
    IGRAPH_EGLP              = 56,
    IGRAPH_CPUTIME           = 57,
    IGRAPH_EUNDERFLOW        = 58,
    IGRAPH_ERWSTUCK          = 59,
    IGRAPH_STOP              = 60  /* undocumented, used internally */
} igraph_error_type_t;

These are the possible values returned by igraph functions. Note that these are interesting only if you defined an error handler with igraph_set_error_handler(). Otherwise the program is aborted and the function causing the error never returns.

Values: 

 const char* igraph_strerror(const int igraph_errno);

This is a simple utility function, it gives a short general textual description for an igraph error code.

Arguments: 

Returns: 

typedef igraph_error_handler_t igraph_warning_handler_t;

Currently it is defined to have the same type as igraph_error_handler_t, although the last (error code) argument is not used.

 igraph_warning_handler_t* igraph_set_warning_handler(igraph_warning_handler_t* new_handler);

Install the supplied warning handler function.

Arguments: 

Returns: 

#define IGRAPH_WARNING(reason)

This is the usual way of triggering a warning from an igraph function. It calls igraph_warning().

Arguments: 

#define IGRAPH_WARNINGF

igraph functions can use this macro when they notice a warning and want to pass on extra information to the user about what went wrong. It calls igraph_warningf() with the proper parameters and no error code.

Arguments: 

 int igraph_warning(const char *reason, const char *file, int line,
                                 int igraph_errno);

Call this function if you want to trigger a warning from within a function that uses igraph.

Arguments: 

Returns: 

 int igraph_warningf(const char *reason, const char *file, int line,
                                  int igraph_errno, ...);

This function is similar to igraph_warning(), but uses a printf-like syntax. It substitutes the additional arguments into the reason template string and calls igraph_warning().

Arguments: 

Returns: 

void igraph_warning_handler_ignore(const char *reason, const char *file,
                                   int line, int igraph_errno);

This warning handler function simply ignores all warnings.

Arguments: 

void igraph_warning_handler_print(const char *reason, const char *file,
                                  int line, int igraph_errno);

This warning handler function simply prints all warnings to the standard error.

Arguments: 

The contents of the rest of this chapter might be useful only for those who want to create an interface to igraph from another language. Most readers can safely skip to the next chapter.

You can write and install error handlers simply by defining a function of type igraph_error_handler_t and calling igraph_set_error_handler(). This feature is useful for interface writers, as igraph will have the chance to signal errors the appropriate way, e.g. the R interface defines an error handler which calls the error() function, as required by R, while the Python interface has an error handler which raises an exception according to the Python way.

If you want to write an error handler, your error handler should call IGRAPH_FINALLY_FREE() to deallocate all temporary memory to prevent memory leaks. Note that this may invalidate the error message buffer reason passed to the error handler. Do not access it after having called IGRAPH_FINALLY_FREE().

 igraph_error_handler_t* igraph_set_error_handler(igraph_error_handler_t* new_handler);

If an error happens, the functions in the library call the IGRAPH_ERROR() macro with a textual description of the error and an igraph error code. This macro calls (through the igraph_error() function) the installed error handler. Another useful macro is IGRAPH_CHECK(). This checks the return value of its argument, which is normally a function call, and calls IGRAPH_ERROR() if it is not IGRAPH_SUCCESS.

#define IGRAPH_ERROR(reason, igraph_errno)

#define IGRAPH_ERRORF

 int igraph_error(const char *reason, const char *file, int line,
                               int igraph_errno);

 int igraph_errorf(const char *reason, const char *file, int line,
                                int igraph_errno, ...);

#define IGRAPH_CHECK(a)

 IGRAPH_CHECK(vector_push_back(&v, 100)); 

If a function runs into an error (and the program is not aborted) the error handler should deallocate all temporary memory. This is done by storing the address and the destroy function of all temporary objects in a stack. The IGRAPH_FINALLY function declares an object as temporary by placing its address in the stack. If an igraph function returns with success it calls IGRAPH_FINALLY_CLEAN() with the number of objects to remove from the stack. If an error happens however, the error handler should call IGRAPH_FINALLY_FREE() to deallocate each object added to the stack. This means that the temporary objects allocated in the calling function (and etc.) will be freed as well.

#define IGRAPH_FINALLY(func, ptr)

 void IGRAPH_FINALLY_CLEAN(int num);

 void IGRAPH_FINALLY_FREE(void);

There are some simple rules to keep in order to have functions behaving well in erroneous situations. First, check the arguments of the functions and call IGRAPH_ERROR() if they are invalid. Second, call IGRAPH_FINALLY on each dynamically allocated object and call IGRAPH_FINALLY_CLEAN() with the proper argument before returning. Third, use IGRAPH_CHECK on all igraph function calls which can generate errors.

The size of the stack used for this bookkeeping is fixed, and small. If you want to allocate several objects, write a destroy function which can deallocate all of these. See the adjlist.c file in the igraph source for an example.

For some functions these mechanisms are simply not flexible enough. These functions should define their own error handlers and restore the error handler before they return.

In some rare situations, igraph may encounter an internal error that cannot be fully handled. In this case, it will call the current fatal error handler. The default fatal error handler simply prints the error and aborts the program.

Fatal error handlers do not return. Typically, they might abort the the program immediately, or in the case of the high-level igraph interfaces, they might return to the top level using a longjmp(). The fatal error handler is only called when a serious error has occurred, and as a result igraph may be in an inconsistent state. The purpose of returning to the top level is to give the user a chance to save their work instead of aborting immediately. However, the program session should be restarted as soon as possible.

Most projects that use igraph will use the default fatal error handler.

typedef void igraph_fatal_handler_t (const char *reason, const char *file, int line);

IGRAPH_EXPORT igraph_fatal_handler_t igraph_fatal_handler_abort;

#define IGRAPH_FATAL(reason)

#define IGRAPH_FATALF

#define IGRAPH_ASSERT(condition)

 IGRAPH_NORETURN void igraph_fatal(const char *reason, const char *file, int line);

 IGRAPH_NORETURN void igraph_fatalf(const char *reason, const char *file, int line, ...);

It is likely that the igraph error handling method is not thread-safe, mainly because of the static global stack which is used to store the address of the temporarily allocated objects. This issue might be addressed in a later version of igraph.