2.1.igraph_error_handler_t — The type of error handler functions.

2.2.igraph_error_handler_abort — Abort program in case of error.

2.3.igraph_error_handler_ignore — Ignore errors.

2.4.igraph_error_handler_printignore — Print and ignore errors.

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

This is the type of the error handler functions.

Arguments: 

IGRAPH_FUNCATTR_NORETURN igraph_error_handler_t igraph_error_handler_abort;

The default error handler, prints an error message and aborts theprogram.

igraph_error_handler_t igraph_error_handler_ignore;

This error handler frees the temporarily allocated memory and returnswith the error code.

igraph_error_handler_t igraph_error_handler_printignore;

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

3.1.igraph_error_t — Return type for functions returning an error code.

3.2.igraph_error_type_t — Error code type.

3.3.igraph_strerror — Textual description of an error.

typedef igraph_error_type_t igraph_error_t;

This type is used as the return type of igraph functions that return anerror code. It is a type alias becauseigraph_error_t used to beanint, and was used slightly differenly thanigraph_error_type_t.

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,   /* unused, reserved */    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_ENEGCYCLE         = 37,    IGRAPH_ENEGLOOP IGRAPH_DEPRECATED_ENUMVAL = IGRAPH_ENEGCYCLE,    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 IGRAPH_DEPRECATED_ENUMVAL = 54,    IGRAPH_EOVERFLOW         = 55,    IGRAPH_EGLP              = 56,    IGRAPH_CPUTIME           = 57,    IGRAPH_EUNDERFLOW        = 58,    IGRAPH_ERWSTUCK          = 59,    IGRAPH_STOP              = 60,    IGRAPH_ERANGE            = 61,    IGRAPH_ENOSOL            = 62} igraph_error_type_t;

These are the possible values returned byigraph functions.Note that these are interesting only if you defined an error handlerwithigraph_set_error_handler(). Otherwise the program is abortedand the function causing the error never returns.

Values: 

const char *igraph_strerror(const igraph_error_t igraph_errno);

This is a simple utility function, it gives a short general textualdescription for anigraph error code.

Arguments: 

Returns: 

4.1.igraph_warning_handler_t — The type of igraph warning handler functions.

4.2.igraph_set_warning_handler — Installs a warning handler.

4.3.IGRAPH_WARNING — Triggers a warning.

4.4.IGRAPH_WARNINGF — Triggers a warning, with printf-like syntax.

4.5.igraph_warning — Reports a warning.

4.6.igraph_warningf — Reports a warning, printf-like version.

4.7.igraph_warning_handler_ignore — Ignores all warnings.

4.8.igraph_warning_handler_print — Prints all warnings to the standard error.

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

Currently it is defined to have the same type asigraph_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 igraphfunction. It callsigraph_warning().

Arguments: 

#define IGRAPH_WARNINGF(reason, ...)

igraph functions can use this macro when they notice a warning andwant to pass on extra information to the user about what went wrong.It callsigraph_warningf() with the proper parameters and noerror code.

Arguments: 

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

Call this function if you want to trigger a warning from withina function that usesigraph.

Arguments: 

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

This function is similar toigraph_warning(), butuses a printf-like syntax. It substitutes the additional argumentsinto thereason template string and callsigraph_warning().

Arguments: 

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

This warning handler function simply ignores all warnings.

Arguments: 

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

This warning handler function simply prints all warnings to thestandard error.

Arguments: 

5.1. Writing error handlers

5.2. Error handling internals

5.3. Deallocating memory

5.4. Writingigraph functions withproper error handling

5.5. Fatal errors

5.6. Error handling and threads

The contents of the rest of this chapter might be useful onlyfor those who want to create an interface toigraph from anotherlanguage, or use igraph from a GUI application. Most readers cansafely skip to the next chapter.

You can write and install error handlers simply by defining afunction of typeigraph_error_handler_t and callingigraph_set_error_handler(). This feature is useful for interfacewriters, asigraph will have the chance tosignal errors the appropriate way. For example, the R interface usesR's native printing facilities to communicate errors, while the Pythoninterface converts them into Python exceptions.

The two main tasks of the error handler are to report the error(i.e. print the error message) and ensure proper resource cleanup.This is ensured by callingIGRAPH_FINALLY_FREE(), which deallocatessome of the temporary memory to avoid memory leaks. Note that this mayinvalidate the error message bufferreason passed to the error handler.Do not access it after having calledIGRAPH_FINALLY_FREE().

As ofigraph 0.10, temporary memory is dellocated in stages, throughmultiple calls to the error handler (and indirectly toIGRAPH_FINALLY_FREE()).Therefore, error handlers that do not abort the programimmediately are expected to return. The error handler should not performalongjmp, as this may lead to some of the memory notgetting freed.

igraph_error_handler_t *igraph_set_error_handler(igraph_error_handler_t *new_handler);

If an error happens, the functions in the library call theIGRAPH_ERROR() macro with a textual description of the error and anigraph error code. This macro calls (through theigraph_error() function) the installed error handler. Another usefulmacro isIGRAPH_CHECK(). This checks the return value of itsargument, which is normally a function call, and callsIGRAPH_ERROR() if it is notIGRAPH_SUCCESS.

#define IGRAPH_ERROR(reason, igraph_errno)

#define IGRAPH_ERRORF(reason, igraph_errno, ...)

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

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

#define IGRAPH_CHECK(expr)

 IGRAPH_CHECK(vector_push_back(&v, 100));

#define IGRAPH_CHECK_CALLBACK(expr, code)

If a function runs into an error (and the program is not aborted)the error handler should deallocate all temporary memory. This isdone by storing the address and the destroy function of all temporaryobjects in a stack. TheIGRAPH_FINALLY function declares an object astemporary by placing its address in the stack. If anigraph function returnswith success it callsIGRAPH_FINALLY_CLEAN() with thenumber of objects to remove from the stack. If an error happenshowever, the error handler should callIGRAPH_FINALLY_FREE() todeallocate each object added to the stack. This means that thetemporary objects allocated in the calling function (and etc.) willbe freed as well.

#define IGRAPH_FINALLY(func, ptr)

IGRAPH_CHECK(igraph_vector_init(&vector, 0));IGRAPH_FINALLY(igraph_vector_destroy, &vector);

IGRAPH_VECTOR_INIT_FINALLY(&vector, 0);

void IGRAPH_FINALLY_CLEAN(int num);

igraph_vector_t vector;igraph_vector_init(&vector, 10);IGRAPH_FINALLY(igraph_vector_destroy, &vector);// use vectorigraph_vector_destroy(&vector);IGRAPH_FINALLY_CLEAN(1);

void IGRAPH_FINALLY_FREE(void);

There are some simple rules to keep in order to have functionsbehaving well in erroneous situations. First, check the argumentsof the functions and callIGRAPH_ERROR() if they are invalid. Second,callIGRAPH_FINALLY on each dynamically allocated object and callIGRAPH_FINALLY_CLEAN() with the proper argument before returning. Third, useIGRAPH_CHECK on alligraph function calls which can generate errors.

The size of the stack used for this bookkeeping is fixed, andsmall. If you want to allocate several objects, write a destroyfunction which can deallocate all of these. See theadjlist.c file in theigraph source for an example.

For some functions these mechanisms are simply not flexibleenough. These functions should define their own error handlers andrestore the error handler before they return.

#include <igraph.h>/* Create the condensation of a directed graph. * Seehttps://en.wikipedia.org/wiki/Strongly_connected_component#Definitions * This example demonstrates how to write a basic igraph function, complete * with error handling. */igraph_error_tcondensation(const igraph_t *graph, igraph_t *cond) {    igraph_vector_int_t membership;/* Data structures such as vector must be initialized in igraph before use. */IGRAPH_CHECK(igraph_vector_int_init(&membership, 0));/* Adding the initialized vector to the "finally" stack ensures that it will     * be automatically destroyed if an error occurs. */IGRAPH_FINALLY(igraph_vector_int_destroy, &membership);/* Functions that return an error code can be wrapped in IGRAPH_CHECK to pass that error     * up to the caller. */IGRAPH_CHECK(igraph_connected_components(graph, &membership,/* csize */ NULL,/* no */ NULL, IGRAPH_STRONG));/* To compute the condensation, we simply contract strongly connected components.     * Since igraph_contract_vertices() modifies graphs in-place, we make a copy first. */IGRAPH_CHECK(igraph_copy(cond, graph));/* Since we are not done creating the condensation yet, we add 'cond' to the     * "finally" stack, so that it will be destroyed if an error occurs. */IGRAPH_FINALLY(igraph_destroy, cond);/* Contract strongly connected components. */IGRAPH_CHECK(igraph_contract_vertices(cond, &membership, NULL));/* igraph_contract_vertices() preserves all edges, some of which become     * parallel edges or self-loops after the contraction. We simplify these. */IGRAPH_CHECK(igraph_simplify(cond,/* remove_multiple */ true,/* remove_loops */ true, NULL));/* Data structures that are no longer needed must be explicitly destroyed.     * If they were added to the "finally" stack, they must be removed explicitly,     * in the opposite order to how they were added. IGRAPH_FINALLY_CLEAN removes     * the indicated number of entries from the "finally" stack. We remove     * 'membership' because it was destroyed, and 'cond' because the responsibility     * to destroy it is now with the caller. */igraph_vector_int_destroy(&membership);IGRAPH_FINALLY_CLEAN(2);return IGRAPH_SUCCESS;/* return with no error */}intmain(void) {    igraph_t graph, cond;/* Create a random directed graph with mean degree 2 and compute its condensation. */igraph_erdos_renyi_game_gnm(&graph, 100, 200, IGRAPH_DIRECTED, IGRAPH_NO_LOOPS);condensation(&graph, &cond);printf("Number of vertices in the condensation: %" IGRAPH_PRId "\n",igraph_vcount(&cond));igraph_write_graph_edgelist(&cond, stdout);/* Destroy data structures that are no longer needed. */igraph_destroy(&graph);igraph_destroy(&cond);return 0;}

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

Fatal error handlers do not return. Typically, they might abort thethe program immediately, or in the case of the high-leveligraphinterfaces, they might return to the top level using alongjmp(). The fatal error handler is only called whena serious error has occurred, and as a result igraph may be in aninconsistent state. The purpose of returning to the top level is togive 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 useigraph will use the default fatal errorhandler.

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

igraph_fatal_handler_t *igraph_set_fatal_handler(igraph_fatal_handler_t *new_handler);

IGRAPH_FUNCATTR_NORETURN igraph_fatal_handler_t igraph_fatal_handler_abort;

#define IGRAPH_FATAL(reason)

#define IGRAPH_FATALF(reason, ...)

#define IGRAPH_ASSERT(condition)

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

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

It is likely that theigraph error handlingmethod isnot thread-safe, mainly because ofthe static global stack which is used to store the address of thetemporarily allocated objects. This issue might be addressed in alater version ofigraph.