Abdelrahman Said
1204 lines
51 KiB
HTML
1204 lines
51 KiB
HTML
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Chapter 34. Advanced igraph programming</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-Nongraph.html" title="Chapter 33. Non-graph related functions">
|
||
<link rel="next" href="igraph-Glossary.html" title="Chapter 35. Glossary">
|
||
<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-Nongraph.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-Glossary.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-Advanced"></a>Chapter 34. Advanced igraph programming</h1></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#using-igraph-in-multi-threaded-programs">1. Using igraph in multi-threaded programs</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph-Progress">2. Progress handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph-Status">3. Status handlers</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="using-igraph-in-multi-threaded-programs"></a>1. Using igraph in multi-threaded programs</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#IGRAPH_THREAD_SAFE">1.1. <code class="function">IGRAPH_THREAD_SAFE</code> — Specifies whether igraph was built in thread-safe mode.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#thread-safe-arpack-library">1.2. Thread-safe ARPACK library</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#thread-safe-rng">1.3. Thread-safety of random number generators</a></span></dt>
|
||
</dl></div>
|
||
<p>
|
||
The igraph library is considered thread-safe if it has been compiled
|
||
with thread-local storage enabled, i.e. the <code class="literal">IGRAPH_ENABLE_TLS</code>
|
||
setting was toggled to <code class="literal">ON</code> and the current platform
|
||
supports this feature. To check whether an igraph build is thread-safe, use the
|
||
<a class="link" href="igraph-Advanced.html#IGRAPH_THREAD_SAFE" title="1.1. IGRAPH_THREAD_SAFE — Specifies whether igraph was built in thread-safe mode.">
|
||
<code class="function">IGRAPH_THREAD_SAFE</code>
|
||
</a>
|
||
macro. When linking to external versions of igraph's dependencies, it is
|
||
the responsibility of the user to check that these dependencies were also
|
||
compiled to be thread-safe.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="IGRAPH_THREAD_SAFE"></a>1.1. <code class="function">IGRAPH_THREAD_SAFE</code> — Specifies whether igraph was built in thread-safe mode.</h3></div></div></div>
|
||
<a class="indexterm" name="id-1.35.2.3.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_THREAD_SAFE
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This macro is defined to 1 if the current build of the igraph library is
|
||
built in thread-safe mode, and 0 if it is not. A thread-safe igraph library
|
||
attempts to use thread-local data structures instead of global ones, but
|
||
note that this is not (and can not) be guaranteed for third-party libraries
|
||
that igraph links to.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="thread-safe-arpack-library"></a>1.2. Thread-safe ARPACK library</h3></div></div></div>
|
||
<p>
|
||
Note that igraph is only thread-safe if it was built with the internal
|
||
ARPACK library, i.e. the one that comes with igraph. The standard
|
||
ARPACK library is not thread-safe.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="thread-safe-rng"></a>1.3. Thread-safety of random number generators</h3></div></div></div>
|
||
<p>
|
||
The default random number generator that igraph uses is <span class="emphasis"><em>not</em></span>
|
||
guaranteed to be thread-safe. You need to set a different random number generator
|
||
instance for every thread that you want to use igraph from. This is especially
|
||
important if you set the seed of the random number generator to ensure
|
||
reproducibility; sharing a random number generator between threads would break
|
||
reproducibility as the order in which the various threads are scheduled is
|
||
random, and therefore they would still receive random numbers in an unpredictable
|
||
order from the shared random number generator.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="igraph-Progress"></a>2. Progress handlers</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#about-progress-handlers">2.1. About progress handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#setting-up-progress-handlers">2.2. Setting up progress handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#invoking-the-progress-handler">2.3. Invoking the progress handler</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#writing-progress-handlers">2.4. Writing progress handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#functions-with-progress">2.5. Writing igraph functions with progress reporting</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#progress-and-threads">2.6. Multi-threaded programs</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="about-progress-handlers"></a>2.1. About progress handlers</h3></div></div></div>
|
||
<p>It is often useful to report the progress of some long
|
||
calculation, to allow the user to follow the computation and
|
||
guess the total running time. A couple of igraph functions
|
||
support this at the time of writing, hopefully more will support it
|
||
in the future.
|
||
</p>
|
||
<p>
|
||
To see the progress of a computation, the user has to install a
|
||
progress handler, as there is none installed by default.
|
||
If an igraph function supports progress reporting, then it
|
||
calls the installed progress handler periodically, and passes a
|
||
percentage value to it, the percentage of computation already
|
||
performed. To install a progress handler, you need to call
|
||
<a class="link" href="igraph-Advanced.html#igraph_set_progress_handler" title="2.2.2. igraph_set_progress_handler — Install a progress handler, or remove the current handler."><code class="function">igraph_set_progress_handler()</code></a>. Currently there is a single
|
||
pre-defined progress handler, called <a class="link" href="igraph-Advanced.html#igraph_progress_handler_stderr" title="2.2.3. igraph_progress_handler_stderr — A simple predefined progress handler."><code class="function">igraph_progress_handler_stderr()</code></a>.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="setting-up-progress-handlers"></a>2.2. Setting up progress handlers</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_progress_handler_t">2.2.1. <code class="function">igraph_progress_handler_t</code> — Type of progress handler functions</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_set_progress_handler">2.2.2. <code class="function">igraph_set_progress_handler</code> — Install a progress handler, or remove the current handler.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_progress_handler_stderr">2.2.3. <code class="function">igraph_progress_handler_stderr</code> — A simple predefined progress handler.</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_progress_handler_t"></a>2.2.1. <code class="function">igraph_progress_handler_t</code> — Type of progress handler functions</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.3.2.2"></a><pre class="programlisting">
|
||
typedef igraph_error_t igraph_progress_handler_t(const char *message, igraph_real_t percent,
|
||
void *data);
|
||
</pre>
|
||
<p>
|
||
|
||
|
||
This is the type of the igraph progress handler functions.
|
||
There is currently one such predefined function,
|
||
<a class="link" href="igraph-Advanced.html#igraph_progress_handler_stderr" title="2.2.3. igraph_progress_handler_stderr — A simple predefined progress handler."><code class="function">igraph_progress_handler_stderr()</code></a>, but the user can
|
||
write and set up more sophisticated ones.
|
||
</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
A string describing the function or algorithm
|
||
that is reporting the progress. Current igraph functions
|
||
always use the name <em class="parameter"><code>message</code></em> argument if reporting from the
|
||
same function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>percent</code></em>:</span></p></td>
|
||
<td><p>
|
||
Numeric, the percentage that was completed by the
|
||
algorithm or function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
User-defined data. Current igraph functions that
|
||
report progress pass a null pointer here. Users can
|
||
write their own progress handlers and functions with progress
|
||
reporting, and then pass some meaningfull context here.
|
||
</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>
|
||
If the return value of the progress handler is not
|
||
<code class="constant">IGRAPH_SUCCESS</code>, then <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> returns the
|
||
error code from the progress handler intact. The <a class="link" href="igraph-Advanced.html#IGRAPH_PROGRESS" title="2.3.1. IGRAPH_PROGRESS — Report the progress of a calculation from an igraph function (macro variant)."><code class="function">IGRAPH_PROGRESS()</code></a>
|
||
macro also frees all allocated memory.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_set_progress_handler"></a>2.2.2. <code class="function">igraph_set_progress_handler</code> — Install a progress handler, or remove the current handler.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.3.3.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_progress_handler_t *
|
||
igraph_set_progress_handler(igraph_progress_handler_t new_handler);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
There is a single simple predefined progress handler:
|
||
<a class="link" href="igraph-Advanced.html#igraph_progress_handler_stderr" title="2.2.3. igraph_progress_handler_stderr — A simple predefined progress handler."><code class="function">igraph_progress_handler_stderr()</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>
|
||
Pointer to a function of type
|
||
<a class="link" href="igraph-Advanced.html#igraph_progress_handler_t" title="2.2.1. igraph_progress_handler_t — Type of progress handler functions"><code class="function">igraph_progress_handler_t</code></a>, the progress handler function to
|
||
install. To uninstall the current progress handler, this argument
|
||
can be a null pointer.
|
||
</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 previously installed progress handler function.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_progress_handler_stderr"></a>2.2.3. <code class="function">igraph_progress_handler_stderr</code> — A simple predefined progress handler.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.3.4.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_progress_handler_stderr(const char *message, igraph_real_t percent,
|
||
void* data);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This simple progress handler first prints <em class="parameter"><code>message</code></em>, and then
|
||
the percentage complete value in a short message to 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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
A string describing the function or algorithm
|
||
that is reporting the progress. Current igraph functions
|
||
always use the same <em class="parameter"><code>message</code></em> argument if reporting from the
|
||
same function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>percent</code></em>:</span></p></td>
|
||
<td><p>
|
||
Numeric, the percentage that was completed by the
|
||
algorithm or function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
User-defined data. Current igraph functions that
|
||
report progress pass a null pointer here. Users can
|
||
write their own progress handlers and functions with progress
|
||
reporting, and then pass some meaningfull context here.
|
||
</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>
|
||
This function always returns with <code class="constant">IGRAPH_SUCCESS</code>.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="invoking-the-progress-handler"></a>2.3. Invoking the progress handler</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#IGRAPH_PROGRESS">2.3.1. <code class="function">IGRAPH_PROGRESS</code> — Report the progress of a calculation from an igraph function (macro variant).</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#IGRAPH_PROGRESSF">2.3.2. <code class="function">IGRAPH_PROGRESSF</code> — Report the progress of a calculation from an igraph function, printf-like (macro variant).</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_progress">2.3.3. <code class="function">igraph_progress</code> — Report the progress of a calculation from an igraph function.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_progressf">2.3.4. <code class="function">igraph_progressf</code> — Report the progress of a calculation from an igraph function, printf-like.</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_PROGRESS"></a>2.3.1. <code class="function">IGRAPH_PROGRESS</code> — Report the progress of a calculation from an igraph function (macro variant).</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.4.2.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_PROGRESS(message, percent, data)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
The standard way to report progress from an igraph 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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
A string, a textual message that references the
|
||
calculation under progress.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>percent</code></em>:</span></p></td>
|
||
<td><p>
|
||
Numeric scalar, the percentage that is complete.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
User-defined data, this can be used in user-defined
|
||
progress handler functions, from user-written igraph functions.
|
||
</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>
|
||
If the return value of the progress handler is not
|
||
<code class="constant">IGRAPH_SUCCESS</code>, then <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> returns the
|
||
error code from the progress handler intact. The <a class="link" href="igraph-Advanced.html#IGRAPH_PROGRESS" title="2.3.1. IGRAPH_PROGRESS — Report the progress of a calculation from an igraph function (macro variant)."><code class="function">IGRAPH_PROGRESS()</code></a>
|
||
macro also frees all allocated memory.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_PROGRESSF"></a>2.3.2. <code class="function">IGRAPH_PROGRESSF</code> — Report the progress of a calculation from an igraph function, printf-like (macro variant).</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.4.3.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_PROGRESSF(args)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This is the more flexible version of <a class="link" href="igraph-Advanced.html#IGRAPH_PROGRESS" title="2.3.1. IGRAPH_PROGRESS — Report the progress of a calculation from an igraph function (macro variant)."><code class="function">IGRAPH_PROGRESS()</code></a>,
|
||
having a printf-like syntax. As this macro takes variable
|
||
number of arguments, they must be all supplied as a single
|
||
argument, enclosed in parentheses. <a class="link" href="igraph-Advanced.html#igraph_progressf" title="2.3.4. igraph_progressf — Report the progress of a calculation from an igraph function, printf-like."><code class="function">igraph_progressf()</code></a> is then
|
||
called with the given 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>args</code></em>:</span></p></td>
|
||
<td><p>
|
||
The arguments to pass to <a class="link" href="igraph-Advanced.html#igraph_progressf" title="2.3.4. igraph_progressf — Report the progress of a calculation from an igraph function, printf-like."><code class="function">igraph_progressf()</code></a>.
|
||
</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>
|
||
If the progress handler returns with a value other than
|
||
<code class="constant">IGRAPH_SUCCESS</code>, then the function that called this
|
||
macro returns as well, with the same error code, after
|
||
cleaning up all allocated memory as needed.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_progress"></a>2.3.3. <code class="function">igraph_progress</code> — Report the progress of a calculation from an igraph function.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.4.4.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_progress(const char *message, igraph_real_t percent, void *data);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
Note that the usual way to report progress is the <a class="link" href="igraph-Advanced.html#IGRAPH_PROGRESS" title="2.3.1. IGRAPH_PROGRESS — Report the progress of a calculation from an igraph function (macro variant)."><code class="function">IGRAPH_PROGRESS</code></a>
|
||
macro, as that takes care of the return value of the progress
|
||
handler.
|
||
</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
A string describing the function or algorithm
|
||
that is reporting the progress. Current igraph functions
|
||
always use the name <em class="parameter"><code>message</code></em> argument if reporting from the
|
||
same function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>percent</code></em>:</span></p></td>
|
||
<td><p>
|
||
Numeric, the percentage that was completed by the
|
||
algorithm or function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
User-defined data. Current igraph functions that
|
||
report progress pass a null pointer here. Users can
|
||
write their own progress handlers and functions with progress
|
||
reporting, and then pass some meaningfull context here.
|
||
</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>
|
||
Error code from the progress handler function, or <code class="constant">IGRAPH_SUCCESS</code>
|
||
if no progress handler function was registered.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_progressf"></a>2.3.4. <code class="function">igraph_progressf</code> — Report the progress of a calculation from an igraph function, printf-like.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.3.4.5.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_progressf(const char *message, igraph_real_t percent, void *data,
|
||
...);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This is a more flexible version of <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a>, with
|
||
a printf-like template string. First the template string
|
||
is filled with the additional arguments and then <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> is called.
|
||
|
||
</p>
|
||
<p>Note that there is an upper limit for the length of
|
||
the <em class="parameter"><code>message</code></em> string, currently 1000 characters.
|
||
</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
A string describing the function or algorithm
|
||
that is reporting the progress. For this function this is a
|
||
template string, using the same syntax as the standard
|
||
<code class="constant">libc</code> <code class="constant">printf</code> function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>percent</code></em>:</span></p></td>
|
||
<td><p>
|
||
Numeric, the percentage that was completed by the
|
||
algorithm or function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
User-defined data. Current igraph functions that
|
||
report progress pass a null pointer here. Users can
|
||
write their own progress handlers and functions with progress
|
||
reporting, and then pass some meaningfull context here.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional argument that were specified in the
|
||
<em class="parameter"><code>message</code></em> argument.
|
||
</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>
|
||
Error code from the progress handler function, or <code class="constant">IGRAPH_SUCCESS</code>
|
||
if no progress handler function was registered.
|
||
\return
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="writing-progress-handlers"></a>2.4. Writing progress handlers</h3></div></div></div>
|
||
<p>
|
||
To write a new progress handler, one needs to create a function of
|
||
type <a class="link" href="igraph-Advanced.html#igraph_progress_handler_t" title="2.2.1. igraph_progress_handler_t — Type of progress handler functions"><code class="function">igraph_progress_handler_t</code></a>. The new progress handler
|
||
can then be installed with the <a class="link" href="igraph-Advanced.html#igraph_set_progress_handler" title="2.2.2. igraph_set_progress_handler — Install a progress handler, or remove the current handler."><code class="function">igraph_set_progress_handler()</code></a>
|
||
function.
|
||
</p>
|
||
<p>
|
||
One can assume that the first progress handler call from a
|
||
calculation will be call with zero as the <em class="parameter"><code>percentage</code></em> argument,
|
||
and the last call from a function will have 100 as the <em class="parameter"><code>percentage</code></em> argument. Note, however, that if an error happens in the
|
||
middle of a computation, then the 100 percent call might be
|
||
omitted.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="functions-with-progress"></a>2.5. Writing igraph functions with progress reporting</h3></div></div></div>
|
||
<p>
|
||
If you want to write a function that uses igraph and supports
|
||
progress reporting, you need to include <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a>
|
||
calls in your function, usually via the <a class="link" href="igraph-Advanced.html#IGRAPH_PROGRESS" title="2.3.1. IGRAPH_PROGRESS — Report the progress of a calculation from an igraph function (macro variant)."><code class="function">IGRAPH_PROGRESS()</code></a>
|
||
macro.
|
||
</p>
|
||
<p>
|
||
It is good practice to always include a call to <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> with a zero <em class="parameter"><code>percentage</code></em> argument, before the
|
||
computation; and another call with 100 <em class="parameter"><code>percentage</code></em> value
|
||
after the computation is completed.
|
||
</p>
|
||
<p>
|
||
It is also good practice <span class="emphasis"><em>not</em></span> to call <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> too
|
||
often, as this would slow down the computation. It might not be
|
||
worth to support progress reporting in functions with linear or
|
||
log-linear time complexity, as these are fast, even with a large
|
||
amount of data. For functions with quadratic or higher time
|
||
complexity make sure that the time complexity of the progress
|
||
reporting is constant or at least linear. In practice this means
|
||
having at most O(n) progress checks and at most 100
|
||
<a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a> calls.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="progress-and-threads"></a>2.6. Multi-threaded programs</h3></div></div></div>
|
||
<p>
|
||
In multi-threaded programs, each thread has its own progress
|
||
handler, if thread-local storage is supported and igraph is
|
||
thread-safe. See the <a class="link" href="igraph-Advanced.html#IGRAPH_THREAD_SAFE" title="1.1. IGRAPH_THREAD_SAFE — Specifies whether igraph was built in thread-safe mode."><code class="function">IGRAPH_THREAD_SAFE</code></a> macro for checking
|
||
whether an igraph build is thread-safe.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="igraph-Status"></a>3. Status handlers</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#about-status-handlers">3.1. Status reporting</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#setting-up-status-handlers">3.2. Setting up status handlers</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#invoking-the-status-handler">3.3. Invoking the status handler</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="about-status-handlers"></a>3.1. Status reporting</h3></div></div></div>
|
||
<p>
|
||
In addition to the possibility of reporting the progress of an
|
||
igraph computation via <a class="link" href="igraph-Advanced.html#igraph_progress" title="2.3.3. igraph_progress — Report the progress of a calculation from an igraph function."><code class="function">igraph_progress()</code></a>, it is also possible
|
||
to report simple status messages from within igraph functions,
|
||
without having to judge how much of the computation was performed
|
||
already. For this one needs to install a status handler function.
|
||
</p>
|
||
<p>
|
||
Status handler functions must be of type <a class="link" href="igraph-Advanced.html#igraph_status_handler_t" title="3.2.1. igraph_status_handler_t — The type of the igraph status handler functions"><code class="function">igraph_status_handler_t</code></a>
|
||
and they can be installed by a call to <a class="link" href="igraph-Advanced.html#igraph_set_status_handler" title="3.2.2. igraph_set_status_handler — Install of uninstall a status handler function."><code class="function">igraph_set_status_handler()</code></a>.
|
||
Currently there is a simple predefined status handler function,
|
||
called <a class="link" href="igraph-Advanced.html#igraph_status_handler_stderr" title="3.2.3. igraph_status_handler_stderr — A simple predefined status handler function."><code class="function">igraph_status_handler_stderr()</code></a>, but the user can define
|
||
new ones.
|
||
</p>
|
||
<p>
|
||
igraph functions report their status via a call to the
|
||
<a class="link" href="igraph-Advanced.html#IGRAPH_STATUS" title="3.3.1. IGRAPH_STATUS — Report the status of an igraph function."><code class="function">IGRAPH_STATUS()</code></a> or the <a class="link" href="igraph-Advanced.html#IGRAPH_STATUSF" title="3.3.2. IGRAPH_STATUSF — Report the status from an igraph function"><code class="function">IGRAPH_STATUSF()</code></a> macro.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="setting-up-status-handlers"></a>3.2. Setting up status handlers</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_status_handler_t">3.2.1. <code class="function">igraph_status_handler_t</code> — The type of the igraph status handler functions</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_set_status_handler">3.2.2. <code class="function">igraph_set_status_handler</code> — Install of uninstall a status handler function.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_status_handler_stderr">3.2.3. <code class="function">igraph_status_handler_stderr</code> — A simple predefined status handler function.</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_status_handler_t"></a>3.2.1. <code class="function">igraph_status_handler_t</code> — The type of the igraph status handler functions</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.3.2.2"></a><pre class="programlisting">
|
||
typedef igraph_error_t igraph_status_handler_t(const char *message, void *data);
|
||
</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
The status message.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional context, with user-defined semantics.
|
||
Existing igraph functions pass a null pointer here.
|
||
</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>
|
||
Error code. The current calculation will abort if you return anything
|
||
else than <code class="constant">IGRAPH_SUCCESS</code> here.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_set_status_handler"></a>3.2.2. <code class="function">igraph_set_status_handler</code> — Install of uninstall a status handler function.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.3.3.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_status_handler_t *
|
||
igraph_set_status_handler(igraph_status_handler_t new_handler);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
To uninstall the currently installed status handler, call
|
||
this function with a null pointer.
|
||
</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 status 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 previously installed status handler function.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_status_handler_stderr"></a>3.2.3. <code class="function">igraph_status_handler_stderr</code> — A simple predefined status handler function.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.3.4.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_status_handler_stderr(const char *message, void *data);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
A simple status handler function that writes the status
|
||
message 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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
The status message.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional context, with user-defined semantics.
|
||
Existing igraph functions pass a null pointer here.
|
||
</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>
|
||
Error code.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="invoking-the-status-handler"></a>3.3. Invoking the status handler</h3></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="igraph-Advanced.html#IGRAPH_STATUS">3.3.1. <code class="function">IGRAPH_STATUS</code> — Report the status of an igraph function.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#IGRAPH_STATUSF">3.3.2. <code class="function">IGRAPH_STATUSF</code> — Report the status from an igraph function</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_status">3.3.3. <code class="function">igraph_status</code> — Reports status from an igraph function.</a></span></dt>
|
||
<dt><span class="section"><a href="igraph-Advanced.html#igraph_statusf">3.3.4. <code class="function">igraph_statusf</code> — Report status, more flexible printf-like version.</a></span></dt>
|
||
</dl></div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_STATUS"></a>3.3.1. <code class="function">IGRAPH_STATUS</code> — Report the status of an igraph function.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.4.2.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_STATUS(message, data)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
Typically this function is called only a handful of times from
|
||
an igraph function. E.g. if an algorithm has three major
|
||
steps, then it is logical to call it three times, to
|
||
signal the three major steps.
|
||
</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
The status message.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional context, with user-defined semantics.
|
||
Existing igraph functions pass a null pointer here.
|
||
</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>
|
||
If the status handler returns with a value other than
|
||
<code class="constant">IGRAPH_SUCCESS</code>, then the function that called this
|
||
macro returns as well, with the same error code, after
|
||
cleaning up all allocated memory as needed.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="IGRAPH_STATUSF"></a>3.3.2. <code class="function">IGRAPH_STATUSF</code> — Report the status from an igraph function</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.4.3.2"></a><p>
|
||
</p>
|
||
<pre class="programlisting">
|
||
#define IGRAPH_STATUSF(args)
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
This is the more flexible version of <a class="link" href="igraph-Advanced.html#IGRAPH_STATUS" title="3.3.1. IGRAPH_STATUS — Report the status of an igraph function."><code class="function">IGRAPH_STATUS()</code></a>,
|
||
having a printf-like syntax. As this macro takes variable
|
||
number of arguments, they must be all supplied as a single
|
||
argument, enclosed in parentheses. <a class="link" href="igraph-Advanced.html#igraph_statusf" title="3.3.4. igraph_statusf — Report status, more flexible printf-like version."><code class="function">igraph_statusf()</code></a> is then
|
||
called with the given 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>args</code></em>:</span></p></td>
|
||
<td><p>
|
||
The arguments to pass to <a class="link" href="igraph-Advanced.html#igraph_statusf" title="3.3.4. igraph_statusf — Report status, more flexible printf-like version."><code class="function">igraph_statusf()</code></a>.
|
||
</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>
|
||
If the status handler returns with a value other than
|
||
<code class="constant">IGRAPH_SUCCESS</code>, then the function that called this
|
||
macro returns as well, with the same error code, after
|
||
cleaning up all allocated memory as needed.
|
||
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_status"></a>3.3.3. <code class="function">igraph_status</code> — Reports status from an igraph function.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.4.4.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_status(const char *message, void *data);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
It calls the installed status handler function, if there is
|
||
one. Otherwise it does nothing. Note that the standard way to
|
||
report the status from an igraph function is the
|
||
<a class="link" href="igraph-Advanced.html#IGRAPH_STATUS" title="3.3.1. IGRAPH_STATUS — Report the status of an igraph function."><code class="function">IGRAPH_STATUS</code></a> or <a class="link" href="igraph-Advanced.html#IGRAPH_STATUSF" title="3.3.2. IGRAPH_STATUSF — Report the status from an igraph function"><code class="function">IGRAPH_STATUSF</code></a> macro, as these
|
||
take care of cleaning up allocated memory from the calling
|
||
function if the status handler returns with an 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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
The status message.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional context, with user-defined semantics.
|
||
Existing igraph functions pass a null pointer here.
|
||
</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>
|
||
Error code from the status handler function, or <code class="constant">IGRAPH_SUCCESS</code>
|
||
if no status handler function was registered.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
Time complexity: O(1).
|
||
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="igraph_statusf"></a>3.3.4. <code class="function">igraph_statusf</code> — Report status, more flexible printf-like version.</h4></div></div></div>
|
||
<a class="indexterm" name="id-1.35.4.4.5.2"></a><p>
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
igraph_error_t igraph_statusf(const char *message, void *data, ...);
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
|
||
|
||
|
||
This is the more flexible version of <a class="link" href="igraph-Advanced.html#igraph_status" title="3.3.3. igraph_status — Reports status from an igraph function."><code class="function">igraph_status()</code></a>,
|
||
that has a syntax similar to the <code class="constant">printf</code> standard C library function.
|
||
It substitutes the values of the additional arguments into the
|
||
<em class="parameter"><code>message</code></em> template string and calls <a class="link" href="igraph-Advanced.html#igraph_status" title="3.3.3. igraph_status — Reports status from an igraph function."><code class="function">igraph_status()</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>message</code></em>:</span></p></td>
|
||
<td><p>
|
||
Status message template string, the syntax is the same
|
||
as for the <code class="constant">printf</code> function.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>data</code></em>:</span></p></td>
|
||
<td><p>
|
||
Additional context, with user-defined semantics.
|
||
Existing igraph functions pass a null pointer here.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><em class="parameter"><code>...</code></em>:</span></p></td>
|
||
<td><p>
|
||
The additional arguments to fill the template given in the
|
||
<em class="parameter"><code>message</code></em> argument.
|
||
</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>
|
||
Error code from the status handler function, or <code class="constant">IGRAPH_SUCCESS</code>
|
||
if no status handler function was registered.
|
||
</p></td>
|
||
</tr></tbody>
|
||
</table></div>
|
||
<p>
|
||
|
||
</p>
|
||
</div>
|
||
</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-Nongraph.html"><b>← Chapter 33. Non-graph related functions </b></a></td>
|
||
<td align="right"><a accesskey="n" href="igraph-Glossary.html"><b>Chapter 35. Glossary →</b></a></td>
|
||
</tr></table>
|
||
</body>
|
||
</html>
|