Abdelrahman Said
2122 lines
89 KiB
HTML
2122 lines
89 KiB
HTML
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Chapter 5. Error handling</title>
|
||
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
||
<link rel="home" href="index.html" title="igraph Reference Manual">
|
||
<link rel="up" href="index.html" title="igraph Reference Manual">
|
||
<link rel="prev" href="igraph-Basic.html" title="Chapter 4. Basic data types and interface">
|
||
<link rel="next" href="igraph-Memory.html" title="Chapter 6. Memory (de)allocation">
|
||
<script type="text/javascript" src="toggle.js"></script><link rel="stylesheet" href="style.css" type="text/css">
|
||
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" type="text/css">
|
||
<link rel="chapter" href="igraph-Introduction.html" title="Chapter 1. Introduction">
|
||
<link rel="chapter" href="igraph-Installation.html" title="Chapter 2. Installation">
|
||
<link rel="chapter" href="igraph-Tutorial.html" title="Chapter 3. Tutorial">
|
||
<link rel="chapter" href="igraph-Basic.html" title="Chapter 4. Basic data types and interface">
|
||
<link rel="chapter" href="igraph-Error.html" title="Chapter 5. Error handling">
|
||
<link rel="chapter" href="igraph-Memory.html" title="Chapter 6. Memory (de)allocation">
|
||
<link rel="chapter" href="igraph-Data-structures.html" title="Chapter 7. Data structure library: vector, matrix, other data types">
|
||
<link rel="chapter" href="igraph-Random.html" title="Chapter 8. Random numbers">
|
||
<link rel="chapter" href="igraph-Iterators.html" title="Chapter 9. Vertex and edge selectors and sequences, iterators">
|
||
<link rel="chapter" href="igraph-Attributes.html" title="Chapter 10. Graph, vertex and edge attributes">
|
||
<link rel="chapter" href="igraph-Generators.html" title="Chapter 11. Deterministic graph generators">
|
||
<link rel="chapter" href="igraph-Games.html" title='Chapter 12. Stochastic graph generators ("games")'>
|
||
<link rel="chapter" href="igraph-Bipartite.html" title="Chapter 13. Bipartite, i.e. two-mode graphs">
|
||
<link rel="chapter" href="igraph-Spatial.html" title="Chapter 14. Spatial graphs">
|
||
<link rel="chapter" href="igraph-Operators.html" title="Chapter 15. Graph operators">
|
||
<link rel="chapter" href="igraph-Visitors.html" title="Chapter 16. Graph visitors">
|
||
<link rel="chapter" href="igraph-Structural.html" title="Chapter 17. Structural properties of graphs">
|
||
<link rel="chapter" href="igraph-Cycles.html" title="Chapter 18. Graph cycles">
|
||
<link rel="chapter" href="igraph-Cliques.html" title="Chapter 19. Cliques and independent vertex sets">
|
||
<link rel="chapter" href="igraph-Motifs.html" title="Chapter 20. Graph motifs, dyad census and triad census">
|
||
<link rel="chapter" href="igraph-Isomorphism.html" title="Chapter 21. Graph isomorphism">
|
||
<link rel="chapter" href="igraph-Coloring.html" title="Chapter 22. Graph coloring">
|
||
<link rel="chapter" href="igraph-Flows.html" title="Chapter 23. Maximum flows, minimum cuts and related measures">
|
||
<link rel="chapter" href="igraph-Separators.html" title="Chapter 24. Vertex separators">
|
||
<link rel="chapter" href="igraph-Community.html" title="Chapter 25. Detecting community structure">
|
||
<link rel="chapter" href="igraph-Graphlets.html" title="Chapter 26. Graphlets">
|
||
<link rel="chapter" href="igraph-HRG.html" title="Chapter 27. Hierarchical random graphs">
|
||
<link rel="chapter" href="igraph-Embedding.html" title="Chapter 28. Embedding of graphs">
|
||
<link rel="chapter" href="igraph-Layout.html" title="Chapter 29. Generating layouts for graph drawing">
|
||
<link rel="chapter" href="igraph-Processes.html" title="Chapter 30. Processes on graphs">
|
||
<link rel="chapter" href="igraph-Foreign.html" title="Chapter 31. Reading and writing graphs from and to files">
|
||
<link rel="chapter" href="igraph-Linalg.html" title="Chapter 32. Using BLAS, LAPACK and ARPACK for igraph matrices and graphs">
|
||
<link rel="chapter" href="igraph-Nongraph.html" title="Chapter 33. Non-graph related functions">
|
||
<link rel="chapter" href="igraph-Advanced.html" title="Chapter 34. Advanced igraph programming">
|
||
<link rel="chapter" href="igraph-Glossary.html" title="Chapter 35. Glossary">
|
||
<link rel="chapter" href="igraph-Licenses.html" title="Chapter 36. Licenses for igraph and this manual">
|
||
<link rel="index" href="ix01.html" title="Index">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<div class="navigation-header mb-4" width="100%" summary="Navigation header"><div class="btn-group">
|
||
<a accesskey="p" class="btn btn-light" href="igraph-Basic.html"><i class="fa fa-chevron-left"></i>
|
||
Previous
|
||
</a><a accesskey="h" class="btn btn-light" href="index.html"><i class="fa fa-home"></i>
|
||
Home
|
||
</a><a accesskey="n" class="btn btn-light" href="igraph-Memory.html"><i class="fa fa-chevron-right"></i>
|
||
Next
|
||
</a>
|
||
</div></div>
|
||
<div class="chapter">
|
||
<div class="titlepage"><div><div><h1 class="title">
|
||
<a name="igraph-Error"></a>Chapter 5. Error handling</h1></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#error-handling-basics">1. Error handling basics</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#error-handlers">2. Error handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#error-codes">3. Error codes</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#warnings">4. Warning messages</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#error-advanced-topics">5. Advanced topics</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="error-handling-basics"></a>1. Error handling basics</h2></div></div></div>
|
||
<p><span class="command"><strong>igraph</strong></span> functions can run into various problems preventing them
|
||
from normal operation. The user might have supplied invalid arguments,
|
||
e.g. a non-square matrix when a square-matrix was expected, or the program
|
||
has run out of memory while some more memory allocation is required, etc.
|
||
</p>
|
||
<p>By default <span class="command"><strong>igraph</strong></span> aborts the program when it runs into an
|
||
error. While this behavior might be good enough for smaller programs,
|
||
it is without doubt avoidable in larger projects. Please read further
|
||
if your project requires more sophisticated error handling. You can
|
||
safely skip the rest of this chapter otherwise.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="error-handlers"></a>2. Error handlers</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_handler_t">2.1. <code class="function">igraph_error_handler_t</code> — The type of error handler functions.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_handler_abort">2.2. <code class="function">igraph_error_handler_abort</code> — Abort program in case of error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_handler_ignore">2.3. <code class="function">igraph_error_handler_ignore</code> — Ignore errors.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_handler_printignore">2.4. <code class="function">igraph_error_handler_printignore</code> — Print and ignore errors.</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
If <span class="command"><strong>igraph</strong></span> runs into an error - an invalid argument was supplied
|
||
to a function, or we've ran out of memory - the control is
|
||
transferred to the <span class="emphasis"><em> error handler </em></span> function.
|
||
</p>
|
||
<p>
|
||
The default error handler is <a class="link" href="igraph-Error.html#igraph_error_handler_abort" title="2.2. igraph_error_handler_abort — Abort program in case of error."><code class="function">igraph_error_handler_abort</code></a> which
|
||
prints an error message and aborts the program.
|
||
</p>
|
||
<p>
|
||
The <a class="link" href="igraph-Error.html#igraph_set_error_handler" title="5.1.1. igraph_set_error_handler — Sets a new error handler."><code class="function">igraph_set_error_handler()</code></a> function can be used to set a new
|
||
error handler function of type <a class="link" href="igraph-Error.html#igraph_error_handler_t" title="2.1. igraph_error_handler_t — The type of error handler functions."><code class="function">igraph_error_handler_t</code></a>; see the
|
||
documentation of this type for details.
|
||
</p>
|
||
<p>
|
||
There are two other predefined error handler functions,
|
||
<a class="link" href="igraph-Error.html#igraph_error_handler_ignore" title="2.3. igraph_error_handler_ignore — Ignore errors."><code class="function">igraph_error_handler_ignore</code></a> and <a class="link" href="igraph-Error.html#igraph_error_handler_printignore" title="2.4. igraph_error_handler_printignore — Print and ignore errors."><code class="function">igraph_error_handler_printignore</code></a>.
|
||
These deallocate the temporarily allocated memory (more about this
|
||
later) and return with the error code. The latter also prints an
|
||
error message. If you use these error handlers you need to take
|
||
care about possible errors yourself by checking the return value of
|
||
(almost) every non-void <span class="command"><strong>igraph</strong></span> function.
|
||
</p>
|
||
<p>
|
||
Independently of the error handler installed, all functions in the
|
||
library do their best to leave their arguments
|
||
<span class="emphasis"><em>semantically</em></span> unchanged if an error
|
||
happens. By semantically we mean that the implementation of an
|
||
object supplied as an argument might change, but its
|
||
<span class="quote">“<span class="quote">meaning</span>”</span> in most cases does not. The rare occasions
|
||
when this rule is violated are documented in this manual.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_handler_t"></a>2.1. <code class="function">igraph_error_handler_t</code> — The type of error handler functions.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.3.7.2"></a><pre class="programlisting">
|
||
typedef void igraph_error_handler_t(const char *reason, const char *file,
|
||
int line, igraph_error_t igraph_errno);
|
||
</pre>
|
||
<p>
|
||
|
||
|
||
This is the type of the error handler functions.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error is noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of the line in the source file which triggered
|
||
the error
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_handler_abort"></a>2.2. <code class="function">igraph_error_handler_abort</code> — Abort program in case of error.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.3.8.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
IGRAPH_FUNCATTR_NORETURN igraph_error_handler_t igraph_error_handler_abort;
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
The default error handler, prints an error message and aborts the
|
||
program.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_handler_ignore"></a>2.3. <code class="function">igraph_error_handler_ignore</code> — Ignore errors.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.3.9.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
igraph_error_handler_t igraph_error_handler_ignore;
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This error handler frees the temporarily allocated memory and returns
|
||
with the error code.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_handler_printignore"></a>2.4. <code class="function">igraph_error_handler_printignore</code> — Print and ignore errors.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.3.10.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
igraph_error_handler_t igraph_error_handler_printignore;
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
Frees temporarily allocated memory, prints an error message to the
|
||
standard error and returns with the error code.
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="error-codes"></a>3. Error codes</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_t">3.1. <code class="function">igraph_error_t</code> — Return type for functions returning an error code.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error_type_t">3.2. <code class="function">igraph_error_type_t</code> — Error code type.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_strerror">3.3. <code class="function">igraph_strerror</code> — Textual description of an error.</a></span></dt>
|
||
</dl></div>
|
||
<p>Every <span class="command"><strong>igraph</strong></span> function which can fail return a
|
||
single integer error code. Some functions are very simple and
|
||
cannot run into any error, these may return other types, or
|
||
<span class="type">void</span> as well. The error codes are defined by the
|
||
<a class="link" href="igraph-Error.html#igraph_error_type_t" title="3.2. igraph_error_type_t — Error code type."><code class="function">igraph_error_type_t</code></a> enumeration.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_t"></a>3.1. <code class="function">igraph_error_t</code> — Return type for functions returning an error code.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.4.3.2"></a><pre class="programlisting">
|
||
typedef igraph_error_type_t igraph_error_t;
|
||
</pre>
|
||
<p>
|
||
|
||
|
||
This type is used as the return type of igraph functions that return an
|
||
error code. It is a type alias because <span class="type">igraph_error_t</span> used to be
|
||
an <code class="constant">int</code>, and was used slightly differenly than <span class="type">igraph_error_type_t</span>.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_error_type_t"></a>3.2. <code class="function">igraph_error_type_t</code> — Error code type.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.4.4.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
typedef enum {
|
||
IGRAPH_SUCCESS = 0,
|
||
IGRAPH_FAILURE = 1,
|
||
IGRAPH_ENOMEM = 2,
|
||
IGRAPH_PARSEERROR = 3,
|
||
IGRAPH_EINVAL = 4,
|
||
IGRAPH_EXISTS = 5,
|
||
/* IGRAPH_EINVEVECTOR = 6, */ /* removed in 1.0 */
|
||
IGRAPH_EINVVID = 7,
|
||
IGRAPH_EINVEID = 8, /* used to be IGRAPH_NONSQUARE before 1.0 */
|
||
IGRAPH_EINVMODE = 9,
|
||
IGRAPH_EFILE = 10,
|
||
IGRAPH_UNIMPLEMENTED = 12,
|
||
IGRAPH_INTERRUPTED = 13,
|
||
IGRAPH_DIVERGED = 14,
|
||
IGRAPH_EARPACK = 15,
|
||
/* ARPACK error codes from 15 to 36 were moved to igraph_arpack_error_t in 1.0 */
|
||
IGRAPH_ENEGCYCLE = 37,
|
||
IGRAPH_EINTERNAL = 38,
|
||
/* ARPACK error codes from 39 to 41 were moved to igraph_arpack_error_t in 1.0 */
|
||
/* IGRAPH_EDIVZERO = 42, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_EBOUND = 43, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_EROOT = 44, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_ENOPFS = 45, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_ENODFS = 46, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_EFAIL = 47, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_EMIPGAP = 48, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_ETMLIM = 49, */ /* removed in 1.0 */
|
||
/* IGRAPH_GLP_ESTOP = 50, */ /* removed in 1.0 */
|
||
/* IGRAPH_EATTRIBUTES = 51, */ /* removed in 1.0 */
|
||
IGRAPH_EATTRCOMBINE = 52,
|
||
/* IGRAPH_ELAPACK = 53, */ /* removed in 1.0 */
|
||
/* IGRAPH_EDRL = 54, */ /* deprecated in 0.10.2, removed in 1.0 */
|
||
IGRAPH_EOVERFLOW = 55,
|
||
/* IGRAPH_EGLP = 56, */ /* removed in 1.0 */
|
||
/* IGRAPH_CPUTIME = 57, */ /* removed in 1.0 */
|
||
IGRAPH_EUNDERFLOW = 58,
|
||
IGRAPH_ERWSTUCK = 59,
|
||
IGRAPH_STOP = 60,
|
||
IGRAPH_ERANGE = 61,
|
||
IGRAPH_ENOSOL = 62
|
||
} igraph_error_type_t;
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
These are the possible values returned by <span class="command"><strong>igraph</strong></span> functions.
|
||
Note that these are interesting only if you defined an error handler
|
||
with <a class="link" href="igraph-Error.html#igraph_set_error_handler" title="5.1.1. igraph_set_error_handler — Sets a new error handler."><code class="function">igraph_set_error_handler()</code></a>. Otherwise the program is aborted
|
||
and the function causing the error never returns.
|
||
|
||
</p>
|
||
<p><b>Values: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_SUCCESS</code>:</span></p></td>
|
||
<td><p>
|
||
The function successfully completed its task.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_FAILURE</code>:</span></p></td>
|
||
<td><p>
|
||
Something went wrong. You'll almost never
|
||
meet this error as normally more specific error codes are used.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ENOMEM</code>:</span></p></td>
|
||
<td><p>
|
||
There wasn't enough memory to allocate
|
||
on the heap.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_PARSEERROR</code>:</span></p></td>
|
||
<td><p>
|
||
A parse error was found in a file.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EINVAL</code>:</span></p></td>
|
||
<td><p>
|
||
A parameter's value is invalid. E.g. negative
|
||
number was specified as the number of vertices.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EXISTS</code>:</span></p></td>
|
||
<td><p>
|
||
A graph/vertex/edge attribute is already
|
||
installed with the given name.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EINVVID</code>:</span></p></td>
|
||
<td><p>
|
||
Invalid vertex ID, negative or too big.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EINVEID</code>:</span></p></td>
|
||
<td><p>
|
||
Invalid edge ID, negative or too big.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EINVMODE</code>:</span></p></td>
|
||
<td><p>
|
||
Invalid mode parameter.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EFILE</code>:</span></p></td>
|
||
<td><p>
|
||
A file operation failed. E.g. a file doesn't exist,
|
||
or the user has no rights to open it.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_UNIMPLEMENTED</code>:</span></p></td>
|
||
<td><p>
|
||
Attempted to call an unimplemented or
|
||
disabled (at compile-time) function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_DIVERGED</code>:</span></p></td>
|
||
<td><p>
|
||
A numeric algorithm failed to converge.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ARPACK</code>:</span></p></td>
|
||
<td><p>
|
||
An error happened inside a calculation implemented
|
||
in ARPACK. The calculation involved is most likely an eigenvector-related
|
||
calculation.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ENEGCYCLE</code>:</span></p></td>
|
||
<td><p>
|
||
Negative cycle detected while calculating shortest paths.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EINTERNAL</code>:</span></p></td>
|
||
<td><p>
|
||
Internal error, likely a bug in igraph.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EATTRCOMBINE</code>:</span></p></td>
|
||
<td><p>
|
||
Unimplemented attribute combination
|
||
method for the given attribute type.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EOVERFLOW</code>:</span></p></td>
|
||
<td><p>
|
||
Integer or double overflow.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_EUNDERFLOW</code>:</span></p></td>
|
||
<td><p>
|
||
Integer or double underflow.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ERWSTUCK</code>:</span></p></td>
|
||
<td><p>
|
||
Random walk got stuck.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ERANGE</code>:</span></p></td>
|
||
<td><p>
|
||
Maximum vertex or edge count exceeded.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="constant">IGRAPH_ENOSOL</code>:</span></p></td>
|
||
<td><p>
|
||
Input problem has no solution.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_strerror"></a>3.3. <code class="function">igraph_strerror</code> — Textual description of an error.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.4.5.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
const char *igraph_strerror(const igraph_error_t igraph_errno);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This is a simple utility function, it gives a short general textual
|
||
description for an <span class="command"><strong>igraph</strong></span> error code.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
pointer to the textual description of the error code.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="warnings"></a>4. Warning messages</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_warning_handler_t">4.1. <code class="function">igraph_warning_handler_t</code> — The type of igraph warning handler functions.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_set_warning_handler">4.2. <code class="function">igraph_set_warning_handler</code> — Installs a warning handler.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_WARNING">4.3. <code class="function">IGRAPH_WARNING</code> — Triggers a warning.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_WARNINGF">4.4. <code class="function">IGRAPH_WARNINGF</code> — Triggers a warning, with printf-like syntax.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_warning">4.5. <code class="function">igraph_warning</code> — Reports a warning.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_warningf">4.6. <code class="function">igraph_warningf</code> — Reports a warning, printf-like version.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_warning_handler_ignore">4.7. <code class="function">igraph_warning_handler_ignore</code> — Ignores all warnings.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_warning_handler_print">4.8. <code class="function">igraph_warning_handler_print</code> — Prints all warnings to the standard error.</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
<span class="command"><strong>igraph</strong></span> also supports warning messages in addition to error
|
||
messages. Warning messages typically do not terminate the
|
||
program, but they are usually crucial to the user.
|
||
</p>
|
||
<p>
|
||
<span class="command"><strong>igraph</strong></span> warnings are handled similarly to errors. There is a
|
||
separate warning handler function that is called whenever
|
||
an <span class="command"><strong>igraph</strong></span> function triggers a warning. This handler can be
|
||
set by the <a class="link" href="igraph-Error.html#igraph_set_warning_handler" title="4.2. igraph_set_warning_handler — Installs a warning handler."><code class="function">igraph_set_warning_handler()</code></a> function. There are
|
||
two predefined simple warning handlers,
|
||
<a class="link" href="igraph-Error.html#igraph_warning_handler_ignore" title="4.7. igraph_warning_handler_ignore — Ignores all warnings."><code class="function">igraph_warning_handler_ignore()</code></a> and
|
||
<a class="link" href="igraph-Error.html#igraph_warning_handler_print" title="4.8. igraph_warning_handler_print — Prints all warnings to the standard error."><code class="function">igraph_warning_handler_print()</code></a>, the latter being the default.
|
||
</p>
|
||
<p>
|
||
To trigger a warning, <span class="command"><strong>igraph</strong></span> functions typically use the
|
||
<a class="link" href="igraph-Error.html#IGRAPH_WARNING" title="4.3. IGRAPH_WARNING — Triggers a warning."><code class="function">IGRAPH_WARNING()</code></a> macro, the <a class="link" href="igraph-Error.html#igraph_warning" title="4.5. igraph_warning — Reports a warning."><code class="function">igraph_warning()</code></a> function,
|
||
or if more flexibility is needed, <a class="link" href="igraph-Error.html#igraph_warningf" title="4.6. igraph_warningf — Reports a warning, printf-like version."><code class="function">igraph_warningf()</code></a>.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_warning_handler_t"></a>4.1. <code class="function">igraph_warning_handler_t</code> — The type of igraph warning handler functions.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.5.2"></a><pre class="programlisting">
|
||
typedef void igraph_warning_handler_t(const char *reason,
|
||
const char *file, int line);
|
||
</pre>
|
||
<p>
|
||
|
||
|
||
Currently it is defined to have the same type as
|
||
<a class="link" href="igraph-Error.html#igraph_error_handler_t" title="2.1. igraph_error_handler_t — The type of error handler functions."><code class="function">igraph_error_handler_t</code></a>, although the last (error code)
|
||
argument is not used.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_set_warning_handler"></a>4.2. <code class="function">igraph_set_warning_handler</code> — Installs a warning handler.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.6.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_warning_handler_t *igraph_set_warning_handler(igraph_warning_handler_t *new_handler);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Install the supplied warning handler function.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>new_handler</code></em>:</span></p></td>
|
||
<td><p>
|
||
The new warning handler function to install.
|
||
Supply a null pointer here to uninstall the current
|
||
warning handler, without installing a new one.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
The current warning handler function.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="IGRAPH_WARNING"></a>4.3. <code class="function">IGRAPH_WARNING</code> — Triggers a warning.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.7.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_WARNING(reason)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This is the usual way of triggering a warning from an igraph
|
||
function. It calls <a class="link" href="igraph-Error.html#igraph_warning" title="4.5. igraph_warning — Reports a warning."><code class="function">igraph_warning()</code></a>.
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
The warning message.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="IGRAPH_WARNINGF"></a>4.4. <code class="function">IGRAPH_WARNINGF</code> — Triggers a warning, with printf-like syntax.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.8.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_WARNINGF(reason, ...)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
<span class="command"><strong>igraph</strong></span> 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 <a class="link" href="igraph-Error.html#igraph_warningf" title="4.6. igraph_warningf — Reports a warning, printf-like version."><code class="function">igraph_warningf()</code></a> with the proper parameters and no
|
||
error code.
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the warning, a template string
|
||
with the same syntax as the standard printf C library function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to be substituted into the
|
||
template string.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_warning"></a>4.5. <code class="function">igraph_warning</code> — Reports a warning.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.9.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_warning(const char *reason, const char *file, int line);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Call this function if you want to trigger a warning from within
|
||
a function that uses <span class="command"><strong>igraph</strong></span>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the warning.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the warning was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the
|
||
warning.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_warningf"></a>4.6. <code class="function">igraph_warningf</code> — Reports a warning, printf-like version.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.10.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_warningf(const char *reason, const char *file, int line, ...);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This function is similar to <a class="link" href="igraph-Error.html#igraph_warning" title="4.5. igraph_warning — Reports a warning."><code class="function">igraph_warning()</code></a>, but
|
||
uses a printf-like syntax. It substitutes the additional arguments
|
||
into the <em class="parameter"><code>reason</code></em> template string and calls <a class="link" href="igraph-Error.html#igraph_warning" title="4.5. igraph_warning — Reports a warning."><code class="function">igraph_warning()</code></a>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the warning, a template string
|
||
with the same syntax as the standard printf C library function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the warning was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the
|
||
warning.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to be substituted into the
|
||
template string.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_warning_handler_ignore"></a>4.7. <code class="function">igraph_warning_handler_ignore</code> — Ignores all warnings.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.11.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_warning_handler_ignore(const char *reason, const char *file, int line);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This warning handler function simply ignores all warnings.
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the warning.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the warning was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the
|
||
warning..</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="igraph_warning_handler_print"></a>4.8. <code class="function">igraph_warning_handler_print</code> — Prints all warnings to the standard error.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.6.5.12.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_warning_handler_print(const char *reason, const char *file, int line);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This warning handler function simply prints all warnings to the
|
||
standard error.
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the warning.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the warning was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the
|
||
warning..</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="error-advanced-topics"></a>5. Advanced topics</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#writing-error-handlers">5.1. Writing error handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#error-handling-internals">5.2. Error handling internals</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#deallocating-memory">5.3. Deallocating memory</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#writing-igraph-functions-with-proper-error-handling">5.4. Writing <span class="command"><strong>igraph</strong></span> functions with
|
||
proper error handling</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#fatal-error-handlers">5.5. Fatal errors</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#error-handling-and-threads">5.6. Error handling and threads</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="writing-error-handlers"></a>5.1. Writing error handlers</h3></div></div></div>
|
||
<div class="toc"><dl class="toc"><dt><span class="section"><a href="igraph-Error.html#igraph_set_error_handler">5.1.1. <code class="function">igraph_set_error_handler</code> — Sets a new error handler.</a></span></dt></dl></div>
|
||
<p>
|
||
The contents of the rest of this chapter might be useful only
|
||
for those who want to create an interface to <span class="command"><strong>igraph</strong></span> from another
|
||
language, or use igraph from a GUI application. Most readers can
|
||
safely skip to the next chapter.
|
||
</p>
|
||
<p>
|
||
You can write and install error handlers simply by defining a
|
||
function of type <a class="link" href="igraph-Error.html#igraph_error_handler_t" title="2.1. igraph_error_handler_t — The type of error handler functions."><code class="function">igraph_error_handler_t</code></a> and calling
|
||
<a class="link" href="igraph-Error.html#igraph_set_error_handler" title="5.1.1. igraph_set_error_handler — Sets a new error handler."><code class="function">igraph_set_error_handler()</code></a>. This feature is useful for interface
|
||
writers, as <span class="command"><strong>igraph</strong></span> will have the chance to
|
||
signal errors the appropriate way. For example, the R interface uses
|
||
R's native printing facilities to communicate errors, while the Python
|
||
interface converts them into Python exceptions.
|
||
</p>
|
||
<p>
|
||
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 calling <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_FREE" title="5.3.3. IGRAPH_FINALLY_FREE — Deallocates objects registered at the current level."><code class="function">IGRAPH_FINALLY_FREE()</code></a>, which deallocates
|
||
some of the temporary memory to avoid memory leaks. Note that this may
|
||
invalidate the error message buffer <em class="parameter"><code>reason</code></em> passed to the error handler.
|
||
Do not access it after having called <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_FREE" title="5.3.3. IGRAPH_FINALLY_FREE — Deallocates objects registered at the current level."><code class="function">IGRAPH_FINALLY_FREE()</code></a>.
|
||
</p>
|
||
<p>
|
||
As of <span class="command"><strong>igraph</strong></span> 0.10, temporary memory is dellocated in stages, through
|
||
multiple calls to the error handler (and indirectly to <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_FREE" title="5.3.3. IGRAPH_FINALLY_FREE — Deallocates objects registered at the current level."><code class="function">IGRAPH_FINALLY_FREE()</code></a>).
|
||
Therefore, error handlers that do not abort the program
|
||
immediately are expected to return. The error handler should not perform
|
||
a <code class="literal">longjmp</code>, as this may lead to some of the memory not
|
||
getting freed.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_set_error_handler"></a>5.1.1. <code class="function">igraph_set_error_handler</code> — Sets a new error handler.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.2.6.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_handler_t *igraph_set_error_handler(igraph_error_handler_t *new_handler);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Installs a new error handler. If called with <code class="constant">NULL</code>, it installs the
|
||
default error handler (which is currently <a class="link" href="igraph-Error.html#igraph_error_handler_abort" title="2.2. igraph_error_handler_abort — Abort program in case of error."><code class="function">igraph_error_handler_abort</code></a>).
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>new_handler</code></em>:</span></p></td>
|
||
<td><p>
|
||
The error handler function to install.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
The old error handler function. This should be saved and
|
||
restored if <em class="parameter"><code>new_handler</code></em> is not needed any
|
||
more.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="error-handling-internals"></a>5.2. Error handling internals</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_ERROR">5.2.1. <code class="function">IGRAPH_ERROR</code> — Triggers an error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_ERRORF">5.2.2. <code class="function">IGRAPH_ERRORF</code> — Triggers an error, with printf-like syntax.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_error">5.2.3. <code class="function">igraph_error</code> — Reports an error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_errorf">5.2.4. <code class="function">igraph_errorf</code> — Reports an error, printf-like version.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_CHECK">5.2.5. <code class="function">IGRAPH_CHECK</code> — Checks the return value of a function call.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_CHECK_CALLBACK">5.2.6. <code class="function">IGRAPH_CHECK_CALLBACK</code> — Checks the return value of a callback.</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
If an error happens, the functions in the library call the
|
||
<a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR()</code></a> macro with a textual description of the error and an
|
||
<span class="command"><strong>igraph</strong></span> error code. This macro calls (through the <a class="link" href="igraph-Error.html#igraph_error" title="5.2.3. igraph_error — Reports an error."><code class="function">igraph_error()</code></a> function) the installed error handler. Another useful
|
||
macro is <a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call."><code class="function">IGRAPH_CHECK()</code></a>. This checks the return value of its
|
||
argument, which is normally a function call, and calls <a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR()</code></a> if it is not <code class="constant">IGRAPH_SUCCESS</code>.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_ERROR"></a>5.2.1. <code class="function">IGRAPH_ERROR</code> — Triggers an error.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.3.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_ERROR(reason, igraph_errno)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
<span class="command"><strong>igraph</strong></span> functions usually use this macro when they notice an error.
|
||
It calls
|
||
<a class="link" href="igraph-Error.html#igraph_error" title="5.2.3. igraph_error — Reports an error."><code class="function">igraph_error()</code></a> with the proper parameters and if that returns
|
||
the macro returns the "calling" function as well, with the error
|
||
code. If for some (suspicious) reason you want to call the error
|
||
handler without returning from the current function, call
|
||
<a class="link" href="igraph-Error.html#igraph_error" title="5.2.3. igraph_error — Reports an error."><code class="function">igraph_error()</code></a> directly.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error. This should be
|
||
something more descriptive than the text associated with the error
|
||
code. E.g. if the error code is <code class="constant">IGRAPH_EINVAL</code>,
|
||
its associated text (see <a class="link" href="igraph-Error.html#igraph_strerror" title="3.3. igraph_strerror — Textual description of an error."><code class="function">igraph_strerror()</code></a>) is "Invalid
|
||
value" and this string should explain which parameter was invalid
|
||
and maybe why.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_ERRORF"></a>5.2.2. <code class="function">IGRAPH_ERRORF</code> — Triggers an error, with printf-like syntax.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.4.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_ERRORF(reason, igraph_errno, ...)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
<span class="command"><strong>igraph</strong></span> functions can use this macro when they notice an error and
|
||
want to pass on extra information to the user about what went wrong.
|
||
It calls <a class="link" href="igraph-Error.html#igraph_errorf" title="5.2.4. igraph_errorf — Reports an error, printf-like version."><code class="function">igraph_errorf()</code></a> with the proper parameters and if that
|
||
returns the macro returns the "calling" function as well, with the
|
||
error code. If for some (suspicious) reason you want to call the
|
||
error handler without returning from the current function, call
|
||
<a class="link" href="igraph-Error.html#igraph_errorf" title="5.2.4. igraph_errorf — Reports an error, printf-like version."><code class="function">igraph_errorf()</code></a> directly.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error, a template string
|
||
with the same syntax as the standard printf C library function.
|
||
This should be something more descriptive than the text associated
|
||
with the error code. E.g. if the error code is <code class="constant">IGRAPH_EINVAL</code>,
|
||
its associated text (see <a class="link" href="igraph-Error.html#igraph_strerror" title="3.3. igraph_strerror — Textual description of an error."><code class="function">igraph_strerror()</code></a>) is "Invalid
|
||
value" and this string should explain which parameter was invalid
|
||
and maybe what was expected and what was recieved.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to be substituted into the
|
||
template string.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_error"></a>5.2.3. <code class="function">igraph_error</code> — Reports an error.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.5.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_error(const char *reason, const char *file, int line,
|
||
igraph_error_t igraph_errno);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
<span class="command"><strong>igraph</strong></span> functions usually call this function (most often via the
|
||
<a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR</code></a> macro) if they notice an error.
|
||
It calls the currently installed error handler function with the
|
||
supplied arguments.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the
|
||
error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
The error code (if it returns).
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
<p><b>See also: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
<a class="link" href="igraph-Error.html#igraph_errorf" title="5.2.4. igraph_errorf — Reports an error, printf-like version."><code class="function">igraph_errorf()</code></a>
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_errorf"></a>5.2.4. <code class="function">igraph_errorf</code> — Reports an error, printf-like version.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.6.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_errorf(const char *reason, const char *file, int line,
|
||
igraph_error_t igraph_errno, ...);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error, interpreted as
|
||
a <code class="constant">printf</code> format string.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The line in the source file which triggered the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>igraph_errno</code></em>:</span></p></td>
|
||
<td><p>
|
||
The <span class="command"><strong>igraph</strong></span> error code.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional parameters, the values to substitute into the
|
||
format string.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
The error code (if it returns).
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
<p><b>See also: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
<a class="link" href="igraph-Error.html#igraph_error" title="5.2.3. igraph_error — Reports an error."><code class="function">igraph_error()</code></a>
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_CHECK"></a>5.2.5. <code class="function">IGRAPH_CHECK</code> — Checks the return value of a function call.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.7.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_CHECK(expr)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>expr</code></em>:</span></p></td>
|
||
<td><p>
|
||
An expression, usually a function call. It is guaranteed to
|
||
be evaluated only once.</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
Executes the expression and checks its value. If this is not
|
||
<code class="constant">IGRAPH_SUCCESS</code>, it calls <a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR</code></a> with
|
||
the value as the error code. Here is an example usage:
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting"> IGRAPH_CHECK(vector_push_back(&v, 100)); </pre></div>
|
||
<p>
|
||
|
||
</p>
|
||
<p>There is only one reason to use this macro when writing
|
||
<span class="command"><strong>igraph</strong></span> functions. If the user installs an error handler which
|
||
returns to the auxiliary calling code (like <a class="link" href="igraph-Error.html#igraph_error_handler_ignore" title="2.3. igraph_error_handler_ignore — Ignore errors."><code class="function">igraph_error_handler_ignore</code></a> and <a class="link" href="igraph-Error.html#igraph_error_handler_printignore" title="2.4. igraph_error_handler_printignore — Print and ignore errors."><code class="function">igraph_error_handler_printignore</code></a>), and the <span class="command"><strong>igraph</strong></span> function
|
||
signalling the error is called from another <span class="command"><strong>igraph</strong></span> function
|
||
then we need to make sure that the error is propagated back to
|
||
the auxiliary (i.e. non-igraph) calling function. This is achieved
|
||
by using <code class="function">IGRAPH_CHECK</code> on every <span class="command"><strong>igraph</strong></span>
|
||
call which can return an error code.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_CHECK_CALLBACK"></a>5.2.6. <code class="function">IGRAPH_CHECK_CALLBACK</code> — Checks the return value of a callback.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.3.8.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_CHECK_CALLBACK(expr, code)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
Identical to <a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call."><code class="function">IGRAPH_CHECK</code></a>, but treats <code class="constant">IGRAPH_STOP</code> as a normal
|
||
(non-erroneous) return code. This macro is used in some igraph functions
|
||
that allow the user to hook into a long-running calculation with a callback
|
||
function. When the user-defined callback function returns <code class="constant">IGRAPH_SUCCESS</code>,
|
||
the calculation will proceed normally. Returning <code class="constant">IGRAPH_STOP</code> from the
|
||
callback will terminate the calculation without reporting an error. Returning
|
||
any other value from the callback is treated as an error code, and igraph
|
||
will trigger the necessary cleanup functions before exiting the function.
|
||
|
||
</p>
|
||
<p>
|
||
Note that <code class="constant">IGRAPH_CHECK_CALLBACK</code> does not handle <code class="constant">IGRAPH_STOP</code> by any
|
||
means except returning it in the variable pointed to by <code class="constant">code</code>. It is the
|
||
responsibility of the caller to handle <code class="constant">IGRAPH_STOP</code> accordingly.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>expr</code></em>:</span></p></td>
|
||
<td><p>
|
||
An expression, usually a call to a user-defined callback function.
|
||
It is guaranteed to be evaluated only once.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>code</code></em>:</span></p></td>
|
||
<td><p>
|
||
Pointer to an optional variable of type <span class="type">igraph_error_t</span>;
|
||
the value of this variable will be set to the error code if it is not a null
|
||
pointer.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="deallocating-memory"></a>5.3. Deallocating memory</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_FINALLY">5.3.1. <code class="function">IGRAPH_FINALLY</code> — Registers an object for deallocation.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_FINALLY_CLEAN">5.3.2. <code class="function">IGRAPH_FINALLY_CLEAN</code> — Signals clean deallocation of objects.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_FINALLY_FREE">5.3.3. <code class="function">IGRAPH_FINALLY_FREE</code> — Deallocates objects registered at the current level.</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
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 <a class="link" href="igraph-Error.html#IGRAPH_FINALLY" title="5.3.1. IGRAPH_FINALLY — Registers an object for deallocation."><code class="function">IGRAPH_FINALLY</code></a> function declares an object as
|
||
temporary by placing its address in the stack. If an <span class="command"><strong>igraph</strong></span> function returns
|
||
with success it calls <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_CLEAN" title="5.3.2. IGRAPH_FINALLY_CLEAN — Signals clean deallocation of objects."><code class="function">IGRAPH_FINALLY_CLEAN()</code></a> with the
|
||
number of objects to remove from the stack. If an error happens
|
||
however, the error handler should call <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_FREE" title="5.3.3. IGRAPH_FINALLY_FREE — Deallocates objects registered at the current level."><code class="function">IGRAPH_FINALLY_FREE()</code></a> 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.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_FINALLY"></a>5.3.1. <code class="function">IGRAPH_FINALLY</code> — Registers an object for deallocation.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.4.3.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_FINALLY(func, ptr)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This macro places the address of an object, together with the
|
||
address of its destructor on a stack. This stack is used if an
|
||
error happens to deallocate temporarily allocated objects to
|
||
prevent memory leaks. After manual deallocation, objects are removed
|
||
from the stack using <a class="link" href="igraph-Error.html#IGRAPH_FINALLY_CLEAN" title="5.3.2. IGRAPH_FINALLY_CLEAN — Signals clean deallocation of objects."><code class="function">IGRAPH_FINALLY_CLEAN()</code></a>.
|
||
|
||
</p>
|
||
<p>
|
||
The typical usage is just after an initialization:
|
||
|
||
</p>
|
||
<pre class="programlisting">
|
||
IGRAPH_CHECK(igraph_vector_init(&vector, 0));
|
||
IGRAPH_FINALLY(igraph_vector_destroy, &vector);
|
||
</pre>
|
||
<p>
|
||
|
||
The most commonly used data structures, such as <a class="link" href="igraph-Data-structures.html#igraph_vector_t" title="2.1. About igraph_vector_t objects"><code class="function">igraph_vector_t</code></a>,
|
||
have associated convenience macros that initialize the object and register
|
||
it on this stack in one step. Thus the pattern above can be replaced with a
|
||
single line:
|
||
|
||
</p>
|
||
<pre class="programlisting">
|
||
IGRAPH_VECTOR_INIT_FINALLY(&vector, 0);
|
||
</pre>
|
||
<p>
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>func</code></em>:</span></p></td>
|
||
<td><p>
|
||
The function which is normally called to
|
||
destroy the object.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>ptr</code></em>:</span></p></td>
|
||
<td><p>
|
||
Pointer to the object itself.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_FINALLY_CLEAN"></a>5.3.2. <code class="function">IGRAPH_FINALLY_CLEAN</code> — Signals clean deallocation of objects.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.4.4.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void IGRAPH_FINALLY_CLEAN(int num);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Removes the specified number of objects from the stack of
|
||
temporarily allocated objects. It is typically called
|
||
immediately after manually destroying the objects:
|
||
|
||
</p>
|
||
<pre class="programlisting">
|
||
igraph_vector_t vector;
|
||
igraph_vector_init(&vector, 10);
|
||
IGRAPH_FINALLY(igraph_vector_destroy, &vector);
|
||
// use vector
|
||
igraph_vector_destroy(&vector);
|
||
IGRAPH_FINALLY_CLEAN(1);
|
||
</pre>
|
||
<p>
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>num</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of objects to remove from the bookkeeping
|
||
stack.</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_FINALLY_FREE"></a>5.3.3. <code class="function">IGRAPH_FINALLY_FREE</code> — Deallocates objects registered at the current level.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.4.5.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void IGRAPH_FINALLY_FREE(void);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Calls the destroy function for all objects in the current level
|
||
of the stack of temporarily allocated objects, i.e. up to the
|
||
nearest mark set by <code class="literal">IGRAPH_FINALLY_ENTER()</code>.
|
||
This function must only be called from an error handler.
|
||
It is <span class="emphasis"><em>not</em></span> appropriate to use it
|
||
instead of destroying each unneeded object of a function, as it
|
||
destroys the temporary objects of the caller function (and so on)
|
||
as well.
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="writing-igraph-functions-with-proper-error-handling"></a>5.4. Writing <span class="command"><strong>igraph</strong></span> functions with
|
||
proper error handling</h3></div></div></div>
|
||
<p>
|
||
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 <a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR()</code></a> if they are invalid. Second,
|
||
call <a class="link" href="igraph-Error.html#IGRAPH_FINALLY" title="5.3.1. IGRAPH_FINALLY — Registers an object for deallocation."><code class="function">IGRAPH_FINALLY</code></a> on each dynamically allocated object and call
|
||
<a class="link" href="igraph-Error.html#IGRAPH_FINALLY_CLEAN" title="5.3.2. IGRAPH_FINALLY_CLEAN — Signals clean deallocation of objects."><code class="function">IGRAPH_FINALLY_CLEAN()</code></a> with the proper argument before returning. Third, use
|
||
<a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call."><code class="function">IGRAPH_CHECK</code></a> on all <span class="command"><strong>igraph</strong></span> function calls which can generate errors.
|
||
</p>
|
||
<p>
|
||
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
|
||
<code class="filename">adjlist.c</code> file in the
|
||
<span class="command"><strong>igraph</strong></span> source for an example.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<div class="hideshow" onClick="toggle(this, event)">
|
||
<div class="example">
|
||
<a name="id-1.6.6.5.5"></a><p class="title"><b>Example 5.1. File <code class="code">examples/simple/igraph_contract_vertices.c</code></b></p>
|
||
<div class="example-contents">
|
||
<pre class="programlisting"><span class="strong"><strong>#include</strong></span> <igraph.h>
|
||
|
||
<span class="emphasis"><em>/* Create the condensation of a directed graph.</em></span>
|
||
<span class="emphasis"><em> * See </em></span>https://en.wikipedia.org/wiki/Strongly_connected_component<span class="emphasis"><em>#Definitions</em></span>
|
||
<span class="emphasis"><em> * This example demonstrates how to write a basic igraph function, complete</em></span>
|
||
<span class="emphasis"><em> * with error handling. */</em></span>
|
||
<a class="link" href="igraph-Error.html#igraph_error_t" title="3.1. igraph_error_t — Return type for functions returning an error code.">igraph_error_t</a> <span class="strong"><strong>condensation</strong></span>(<span class="strong"><strong>const</strong></span> igraph_t *graph, igraph_t *cond) {
|
||
igraph_vector_int_t membership;
|
||
|
||
<span class="emphasis"><em>/* Data structures such as vector must be initialized in igraph before use. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call.">IGRAPH_CHECK</a></strong></span>(<span class="strong"><strong>igraph_vector_int_init</strong></span>(&membership, 0));
|
||
|
||
<span class="emphasis"><em>/* Adding the initialized vector to the "finally" stack ensures that it will</em></span>
|
||
<span class="emphasis"><em> * be automatically destroyed if an error occurs. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_FINALLY" title="5.3.1. IGRAPH_FINALLY — Registers an object for deallocation.">IGRAPH_FINALLY</a></strong></span>(igraph_vector_int_destroy, &membership);
|
||
|
||
<span class="emphasis"><em>/* Functions that return an error code can be wrapped in IGRAPH_CHECK to pass that error</em></span>
|
||
<span class="emphasis"><em> * up to the caller. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call.">IGRAPH_CHECK</a></strong></span>(<span class="strong"><strong><a class="link" href="igraph-Structural.html#igraph_connected_components" title="8.2. igraph_connected_components — Calculates the (weakly or strongly) connected components in a graph.">igraph_connected_components</a></strong></span>(graph, &membership, <span class="emphasis"><em>/* csize */</em></span> NULL, <span class="emphasis"><em>/* no */</em></span> NULL, IGRAPH_STRONG));
|
||
|
||
<span class="emphasis"><em>/* To compute the condensation, we simply contract strongly connected components.</em></span>
|
||
<span class="emphasis"><em> * Since igraph_contract_vertices() modifies graphs in-place, we make a copy first. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call.">IGRAPH_CHECK</a></strong></span>(<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_copy" title="5.1.3. igraph_copy — Creates an exact (deep) copy of a graph.">igraph_copy</a></strong></span>(cond, graph));
|
||
|
||
<span class="emphasis"><em>/* Since we are not done creating the condensation yet, we add 'cond' to the</em></span>
|
||
<span class="emphasis"><em> * "finally" stack, so that it will be destroyed if an error occurs. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_FINALLY" title="5.3.1. IGRAPH_FINALLY — Registers an object for deallocation.">IGRAPH_FINALLY</a></strong></span>(<a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a>, cond);
|
||
|
||
<span class="emphasis"><em>/* Contract strongly connected components. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call.">IGRAPH_CHECK</a></strong></span>(<span class="strong"><strong><a class="link" href="igraph-Operators.html#igraph_contract_vertices" title="3.2. igraph_contract_vertices — Replace multiple vertices with a single one.">igraph_contract_vertices</a></strong></span>(cond, &membership, NULL));
|
||
|
||
<span class="emphasis"><em>/* igraph_contract_vertices() preserves all edges, some of which become</em></span>
|
||
<span class="emphasis"><em> * parallel edges or self-loops after the contraction. We simplify these. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_CHECK" title="5.2.5. IGRAPH_CHECK — Checks the return value of a function call.">IGRAPH_CHECK</a></strong></span>(<span class="strong"><strong><a class="link" href="igraph-Operators.html#igraph_simplify" title="3.11. igraph_simplify — Removes loop and/or multiple edges from the graph.">igraph_simplify</a></strong></span>(cond, <span class="emphasis"><em>/* remove_multiple */</em></span> true, <span class="emphasis"><em>/* remove_loops */</em></span> true, NULL));
|
||
|
||
<span class="emphasis"><em>/* Data structures that are no longer needed must be explicitly destroyed.</em></span>
|
||
<span class="emphasis"><em> * If they were added to the "finally" stack, they must be removed explicitly,</em></span>
|
||
<span class="emphasis"><em> * in the opposite order to how they were added. IGRAPH_FINALLY_CLEAN removes</em></span>
|
||
<span class="emphasis"><em> * the indicated number of entries from the "finally" stack. We remove</em></span>
|
||
<span class="emphasis"><em> * 'membership' because it was destroyed, and 'cond' because the responsibility</em></span>
|
||
<span class="emphasis"><em> * to destroy it is now with the caller. */</em></span>
|
||
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&membership);
|
||
<span class="strong"><strong><a class="link" href="igraph-Error.html#IGRAPH_FINALLY_CLEAN" title="5.3.2. IGRAPH_FINALLY_CLEAN — Signals clean deallocation of objects.">IGRAPH_FINALLY_CLEAN</a></strong></span>(2);
|
||
|
||
<span class="strong"><strong>return</strong></span> IGRAPH_SUCCESS; <span class="emphasis"><em>/* return with no error */</em></span>
|
||
}
|
||
|
||
int <span class="strong"><strong>main</strong></span>(void) {
|
||
igraph_t graph, cond;
|
||
|
||
<span class="emphasis"><em>/* Initialize the library. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_setup" title="4.1. igraph_setup — Initializes the igraph library.">igraph_setup</a></strong></span>();
|
||
|
||
<span class="emphasis"><em>/* Create a random directed graph with mean degree 2 and compute its condensation. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Games.html#igraph_erdos_renyi_game_gnm" title="1.1. igraph_erdos_renyi_game_gnm — Generates a random (Erdős-Rényi) graph with a fixed number of edges.">igraph_erdos_renyi_game_gnm</a></strong></span>(&graph, 100, 200, IGRAPH_DIRECTED, IGRAPH_SIMPLE_SW, IGRAPH_EDGE_UNLABELED);
|
||
<span class="strong"><strong>condensation</strong></span>(&graph, &cond);
|
||
|
||
<span class="strong"><strong>printf</strong></span>("Number of vertices in the condensation: %" IGRAPH_PRId "\n", <span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_vcount" title="5.2.1. igraph_vcount — The number of vertices in a graph.">igraph_vcount</a></strong></span>(&cond));
|
||
<span class="strong"><strong><a class="link" href="igraph-Foreign.html#igraph_write_graph_edgelist" title="1.2. igraph_write_graph_edgelist — Writes the edge list of a graph to a file.">igraph_write_graph_edgelist</a></strong></span>(&cond, stdout);
|
||
|
||
<span class="emphasis"><em>/* Destroy data structures that are no longer needed. */</em></span>
|
||
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&graph);
|
||
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&cond);
|
||
|
||
<span class="strong"><strong>return</strong></span> 0;
|
||
}
|
||
</pre>
|
||
<p></p>
|
||
</div>
|
||
</div>
|
||
<br class="example-break">
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="fatal-error-handlers"></a>5.5. Fatal errors</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_fatal_handler_t">5.5.1. <code class="function">igraph_fatal_handler_t</code> — The type of igraph fatal error handler functions.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_set_fatal_handler">5.5.2. <code class="function">igraph_set_fatal_handler</code> — Installs a fatal error handler.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_fatal_handler_abort">5.5.3. <code class="function">igraph_fatal_handler_abort</code> — Abort program in case of fatal error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_FATAL">5.5.4. <code class="function">IGRAPH_FATAL</code> — Triggers a fatal error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_FATALF">5.5.5. <code class="function">IGRAPH_FATALF</code> — Triggers a fatal error, with printf-like syntax.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#IGRAPH_ASSERT">5.5.6. <code class="function">IGRAPH_ASSERT</code> — igraph-specific replacement for <code class="literal">assert()</code>.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_fatal">5.5.7. <code class="function">igraph_fatal</code> — Triggers a fatal error.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Error.html#igraph_fatalf">5.5.8. <code class="function">igraph_fatalf</code> — Triggers a fatal error, printf-like syntax.</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
In some rare situations, <span class="command"><strong>igraph</strong></span> 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.
|
||
</p>
|
||
<p>
|
||
Fatal error handlers do not return. Typically, they might abort the
|
||
the program immediately, or in the case of the high-level <span class="command"><strong>igraph</strong></span>
|
||
interfaces, they might return to the top level using a
|
||
<code class="literal">longjmp()</code>. 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.
|
||
</p>
|
||
<p>
|
||
Most projects that use <span class="command"><strong>igraph</strong></span> will use the default fatal error
|
||
handler.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_fatal_handler_t"></a>5.5.1. <code class="function">igraph_fatal_handler_t</code> — The type of igraph fatal error handler functions.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.5.2"></a><pre class="programlisting">
|
||
typedef void igraph_fatal_handler_t(const char *reason, const char *file, int line);
|
||
</pre>
|
||
<p>
|
||
|
||
|
||
Functions of this type <span class="emphasis"><em>must</em></span> not return. Typically they
|
||
call <code class="literal">abort()</code> or do a <code class="literal">longjmp()</code>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error is noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of the line in the source file which triggered the error.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_set_fatal_handler"></a>5.5.2. <code class="function">igraph_set_fatal_handler</code> — Installs a fatal error handler.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.6.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_fatal_handler_t *igraph_set_fatal_handler(igraph_fatal_handler_t *new_handler);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Installs the supplied fatal error handler function.
|
||
|
||
</p>
|
||
<p>
|
||
Fatal error handler functions <span class="emphasis"><em>must</em></span> not return. Typically, the fatal
|
||
error handler would either call <code class="literal">abort()</code> or <code class="literal">longjmp()</code>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>new_handler</code></em>:</span></p></td>
|
||
<td><p>
|
||
The new fatal error handler function to install.
|
||
Supply a null pointer here to uninstall the current
|
||
fatal error handler, without installing a new one.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
<p><b>Returns: </b></p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
|
||
<td><p>
|
||
The current fatal error handler function.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_fatal_handler_abort"></a>5.5.3. <code class="function">igraph_fatal_handler_abort</code> — Abort program in case of fatal error.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.7.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
IGRAPH_FUNCATTR_NORETURN igraph_fatal_handler_t igraph_fatal_handler_abort;
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
The default fatal error handler, prints an error message and aborts the program.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_FATAL"></a>5.5.4. <code class="function">IGRAPH_FATAL</code> — Triggers a fatal error.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.8.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_FATAL(reason)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This is the usual way of triggering a fatal error from an igraph
|
||
function. It calls <a class="link" href="igraph-Error.html#igraph_fatal" title="5.5.7. igraph_fatal — Triggers a fatal error."><code class="function">igraph_fatal()</code></a>.
|
||
|
||
</p>
|
||
<p>
|
||
Use this macro only in situations where the error cannot be handled.
|
||
The normal way to handle errors is <a class="link" href="igraph-Error.html#IGRAPH_ERROR" title="5.2.1. IGRAPH_ERROR — Triggers an error."><code class="function">IGRAPH_ERROR()</code></a>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
The error message.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_FATALF"></a>5.5.5. <code class="function">IGRAPH_FATALF</code> — Triggers a fatal error, with printf-like syntax.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.9.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_FATALF(reason, ...)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
<span class="command"><strong>igraph</strong></span> functions can use this macro when a fatal error occurs and
|
||
want to pass on extra information to the user about what went wrong.
|
||
It calls <a class="link" href="igraph-Error.html#igraph_fatalf" title="5.5.8. igraph_fatalf — Triggers a fatal error, printf-like syntax."><code class="function">igraph_fatalf()</code></a> with the proper parameters.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error, a template string
|
||
with the same syntax as the standard printf C library function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to be substituted into the
|
||
template string.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_ASSERT"></a>5.5.6. <code class="function">IGRAPH_ASSERT</code> — igraph-specific replacement for <code class="literal">assert()</code>.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.10.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_ASSERT(condition)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This macro is like the standard <code class="literal">assert()</code>, but instead of
|
||
calling <code class="literal">abort()</code>, it calls <a class="link" href="igraph-Error.html#igraph_fatal" title="5.5.7. igraph_fatal — Triggers a fatal error."><code class="function">igraph_fatal()</code></a>. This allows for returning
|
||
the control to the calling program, e.g. returning to the top level in a high-level
|
||
<span class="command"><strong>igraph</strong></span> interface.
|
||
|
||
</p>
|
||
<p>
|
||
Unlike <code class="literal">assert()</code>, <code class="literal">IGRAPH_ASSERT()</code> is not disabled
|
||
when the <code class="constant">NDEBUG</code> macro is defined.
|
||
|
||
</p>
|
||
<p>
|
||
This macro is meant for internal use by <span class="command"><strong>igraph</strong></span>.
|
||
|
||
</p>
|
||
<p>
|
||
Since a typical fatal error handler does a <code class="literal">longjmp()</code>, avoid using this
|
||
macro in C++ code. With most compilers, destructor will not be called when
|
||
<code class="literal">longjmp()</code> leaves the current scope.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody><tr>
|
||
<td><p><span class="term"><em class="parameter"><code>condition</code></em>:</span></p></td>
|
||
<td><p>
|
||
The condition to be checked.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_fatal"></a>5.5.7. <code class="function">igraph_fatal</code> — Triggers a fatal error.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.11.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_fatal(const char *reason, const char *file, int line);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This function triggers a fatal error. Typically it is called indirectly through
|
||
<a class="link" href="igraph-Error.html#IGRAPH_FATAL" title="5.5.4. IGRAPH_FATAL — Triggers a fatal error."><code class="function">IGRAPH_FATAL()</code></a> or <a class="link" href="igraph-Error.html#IGRAPH_ASSERT" title="5.5.6. IGRAPH_ASSERT — igraph-specific replacement for assert()."><code class="function">IGRAPH_ASSERT()</code></a>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the error.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_fatalf"></a>5.5.8. <code class="function">igraph_fatalf</code> — Triggers a fatal error, printf-like syntax.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.6.6.6.12.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
void igraph_fatalf(const char *reason, const char *file, int line, ...);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This function is similar to <a class="link" href="igraph-Error.html#igraph_fatal" title="5.5.7. igraph_fatal — Triggers a fatal error."><code class="function">igraph_fatal()</code></a>, but
|
||
uses a printf-like syntax. It substitutes the additional arguments
|
||
into the <em class="parameter"><code>reason</code></em> template string and calls <a class="link" href="igraph-Error.html#igraph_fatal" title="5.5.7. igraph_fatal — Triggers a fatal error."><code class="function">igraph_fatal()</code></a>.
|
||
|
||
</p>
|
||
<p><b>Arguments: </b>
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>reason</code></em>:</span></p></td>
|
||
<td><p>
|
||
Textual description of the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>file</code></em>:</span></p></td>
|
||
<td><p>
|
||
The source file in which the error was noticed.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>line</code></em>:</span></p></td>
|
||
<td><p>
|
||
The number of line in the source file which triggered the error.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to be substituted into the template string.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="error-handling-and-threads"></a>5.6. Error handling and threads</h3></div></div></div>
|
||
<p>
|
||
It is likely that the <span class="command"><strong>igraph</strong></span> error handling
|
||
method is <span class="emphasis"><em>not</em></span> 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 <span class="command"><strong>igraph</strong></span>.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<table class="navigation-footer" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle">
|
||
<td align="left"><a accesskey="p" href="igraph-Basic.html"><b>← Chapter 4. Basic data types and interface</b></a></td>
|
||
<td align="right"><a accesskey="n" href="igraph-Memory.html"><b>Chapter 6. Memory (de)allocation →</b></a></td>
|
||
</tr></table>
|
||
</body>
|
||
</html>
|