abdelrahman/agent_compositor_test
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1325902f14a8f17e268a4242528a49b6cf591fa9
agent_compositor_test/references/igraph-1.0.1/doc/html/igraph-Error.html
T
Abdelrahman Said a11edf0c53 Add graph references
2026-06-28 13:49:01 +01:00

2122 lines
89 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<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(&amp;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(&amp;vector, 0));
IGRAPH_FINALLY(igraph_vector_destroy, &amp;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(&amp;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(&amp;vector, 10);
IGRAPH_FINALLY(igraph_vector_destroy, &amp;vector);
// use vector
igraph_vector_destroy(&amp;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> &lt;igraph.h&gt;
<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>(&amp;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, &amp;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, &amp;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, &amp;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>(&amp;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>(&amp;graph, 100, 200, IGRAPH_DIRECTED, IGRAPH_SIMPLE_SW, IGRAPH_EDGE_UNLABELED);
<span class="strong"><strong>condensation</strong></span>(&amp;graph, &amp;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>(&amp;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>(&amp;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>(&amp;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>(&amp;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>
Reference in New Issue View Git Blame Copy Permalink