| Server IP : 182.53.201.61 / Your IP : 216.73.217.175 Web Server : Apache/2.2.15 (Fedora) System : Linux km10.dyndns.org 2.6.31.5-127.fc12.i686.PAE #1 SMP Sat Nov 7 21:25:57 EST 2009 i686 User : apache ( 48) PHP Version : 5.3.3 Disable Function : NONE MySQL : ON | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/gtk-doc/html/gio/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GCancellable</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="async.html" title="Asynchronous I/O">
<link rel="prev" href="async.html" title="Asynchronous I/O">
<link rel="next" href="GAsyncResult.html" title="GAsyncResult">
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="part" href="pt01.html" title="Part I. GIO Overview">
<link rel="chapter" href="ch01.html" title="Introduction">
<link rel="chapter" href="ch02.html" title="Compiling GIO applications">
<link rel="chapter" href="ch03.html" title="Running GIO applications">
<link rel="chapter" href="extending-gio.html" title="Extending GIO">
<link rel="part" href="pt02.html" title="Part II. API Reference">
<link rel="chapter" href="file_ops.html" title="File Operations">
<link rel="chapter" href="file_mon.html" title="File System Monitoring">
<link rel="chapter" href="async.html" title="Asynchronous I/O">
<link rel="chapter" href="streaming.html" title="Streaming I/O">
<link rel="chapter" href="types.html" title="File types and applications">
<link rel="chapter" href="volume_mon.html" title="Volumes and Drives">
<link rel="chapter" href="icons.html" title="Icons">
<link rel="chapter" href="failable_initialization.html" title="Failable Initialization">
<link rel="chapter" href="networking.html" title="Lowlevel platform-independent network support">
<link rel="chapter" href="resolver.html" title="DNS resolution">
<link rel="chapter" href="highlevel-socket.html" title="Highlevel network functionallity">
<link rel="chapter" href="utils.html" title="Utilities">
<link rel="chapter" href="extending.html" title="Extending GIO">
<link rel="part" href="migrating.html" title="Part III. Migrating to GIO">
<link rel="chapter" href="ch18.html" title="Migrating from POSIX to GIO">
<link rel="chapter" href="ch19.html" title="Migrating from GnomeVFS to GIO">
<link rel="chapter" href="gio-hierarchy.html" title="Object Hierarchy">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.18">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.20">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.22">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="async.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="async.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GIO Reference Manual</th>
<td><a accesskey="n" href="GAsyncResult.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#GCancellable.synopsis" class="shortcut">Top</a>
|
<a href="#GCancellable.description" class="shortcut">Description</a>
|
<a href="#GCancellable.object-hierarchy" class="shortcut">Object Hierarchy</a>
|
<a href="#GCancellable.signals" class="shortcut">Signals</a>
</td></tr>
</table>
<div class="refentry" title="GCancellable">
<a name="GCancellable"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="GCancellable.top_of_page"></a>GCancellable</span></h2>
<p>GCancellable — Thread-safe Operation Cancellation Stack</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv" title="Synopsis">
<a name="GCancellable.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include <gio/gio.h>
<a class="link" href="GCancellable.html#GCancellable-struct" title="GCancellable">GCancellable</a>;
<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> * <a class="link" href="GCancellable.html#g-cancellable-new" title="g_cancellable_new ()">g_cancellable_new</a> (void);
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> <a class="link" href="GCancellable.html#g-cancellable-is-cancelled" title="g_cancellable_is_cancelled ()">g_cancellable_is_cancelled</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> <a class="link" href="GCancellable.html#g-cancellable-set-error-if-cancelled" title="g_cancellable_set_error_if_cancelled ()">g_cancellable_set_error_if_cancelled</a>
(<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"
>GError</a> **error);
int <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()">g_cancellable_get_fd</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()">g_cancellable_make_pollfd</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"
>GPollFD</a> *pollfd);
void <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()">g_cancellable_release_fd</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> * <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()">g_cancellable_get_current</a> (void);
void <a class="link" href="GCancellable.html#g-cancellable-pop-current" title="g_cancellable_pop_current ()">g_cancellable_pop_current</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
void <a class="link" href="GCancellable.html#g-cancellable-push-current" title="g_cancellable_push_current ()">g_cancellable_push_current</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
void <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()">g_cancellable_reset</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"
>gulong</a> <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()">g_cancellable_connect</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"
>GCallback</a> callback,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> data_destroy_func);
void <a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()">g_cancellable_disconnect</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"
>gulong</a> handler_id);
void <a class="link" href="GCancellable.html#g-cancellable-cancel" title="g_cancellable_cancel ()">g_cancellable_cancel</a> (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);
</pre>
</div>
<div class="refsect1" title="Object Hierarchy">
<a name="GCancellable.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="synopsis">
<a
href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"
>GObject</a>
+----GCancellable
</pre>
</div>
<div class="refsect1" title="Signals">
<a name="GCancellable.signals"></a><h2>Signals</h2>
<pre class="synopsis">
"<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'>cancelled</a>" : Run Last
</pre>
</div>
<div class="refsect1" title="Description">
<a name="GCancellable.description"></a><h2>Description</h2>
<p>
GCancellable is a thread-safe operation cancellation stack used
throughout GIO to allow for cancellation of synchronous and
asynchronous operations.</p>
<p>
</p>
</div>
<div class="refsect1" title="Details">
<a name="GCancellable.details"></a><h2>Details</h2>
<div class="refsect2" title="GCancellable">
<a name="GCancellable-struct"></a><h3>GCancellable</h3>
<pre class="programlisting">typedef struct _GCancellable GCancellable;</pre>
<p>
Allows actions to be cancelled.</p>
<p>
</p>
</div>
<hr>
<div class="refsect2" title="g_cancellable_new ()">
<a name="g-cancellable-new"></a><h3>g_cancellable_new ()</h3>
<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> * g_cancellable_new (void);</pre>
<p>
Creates a new <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.
</p>
<p>
Applications that want to start one or more operations
that should be cancellable should create a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>
and pass it to the operations.
</p>
<p>
One <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> can be used in multiple consecutive
operations, but not in multiple concurrent operations.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_is_cancelled ()">
<a name="g-cancellable-is-cancelled"></a><h3>g_cancellable_is_cancelled ()</h3>
<pre class="programlisting"><a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> g_cancellable_is_cancelled (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Checks if a cancellable job has been cancelled.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or NULL.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE--CAPS"
><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> is cancelled,
FALSE if called with <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a> or if item is not cancelled.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_set_error_if_cancelled ()">
<a name="g-cancellable-set-error-if-cancelled"></a><h3>g_cancellable_set_error_if_cancelled ()</h3>
<pre class="programlisting"><a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> g_cancellable_set_error_if_cancelled
(<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"
>GError</a> **error);</pre>
<p>
If the <em class="parameter"><code>cancellable</code></em> is cancelled, sets the error to notify
that the operation was cancelled.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td> <a
href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"
><span class="type">GError</span></a> to append error state to.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE--CAPS"
><code class="literal">TRUE</code></a> if <em class="parameter"><code>cancellable</code></em> was cancelled, <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a> if it was not.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_get_fd ()">
<a name="g-cancellable-get-fd"></a><h3>g_cancellable_get_fd ()</h3>
<pre class="programlisting">int g_cancellable_get_fd (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Gets the file descriptor for a cancellable job. This can be used to
implement cancellable operations on Unix systems. The returned fd will
turn readable when <em class="parameter"><code>cancellable</code></em> is cancelled.
</p>
<p>
You are not supposed to read from the fd yourself, just check for
readable status. Reading to unset the readable status is done
with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>.
</p>
<p>
After a successful return from this function, you should use
<a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a> to free up resources allocated for
the returned file descriptor.
</p>
<p>
See also <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> A valid file descriptor. <code class="literal">-1</code> if the file descriptor
is not supported, or on errors.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_make_pollfd ()">
<a name="g-cancellable-make-pollfd"></a><h3>g_cancellable_make_pollfd ()</h3>
<pre class="programlisting"><a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"
>gboolean</a> g_cancellable_make_pollfd (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"
>GPollFD</a> *pollfd);</pre>
<p>
Creates a <a
href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"
><span class="type">GPollFD</span></a> corresponding to <em class="parameter"><code>cancellable</code></em>; this can be passed
to <a
href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-poll"
><code class="function">g_poll()</code></a> and used to poll for cancellation. This is useful both
for unix systems without a native poll and for portability to
windows.
</p>
<p>
When this function returns <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE--CAPS"
><code class="literal">TRUE</code></a>, you should use
<a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a> to free up resources allocated for the
<em class="parameter"><code>pollfd</code></em>. After a <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a> return, do not call <a class="link" href="GCancellable.html#g-cancellable-release-fd" title="g_cancellable_release_fd ()"><code class="function">g_cancellable_release_fd()</code></a>.
</p>
<p>
If this function returns <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a>, either no <em class="parameter"><code>cancellable</code></em> was given or
resource limits prevent this function from allocating the necessary
structures for polling. (On Linux, you will likely have reached
the maximum number of file descriptors.) The suggested way to handle
these cases is to ignore the <em class="parameter"><code>cancellable</code></em>.
</p>
<p>
You are not supposed to read from the fd yourself, just check for
readable status. Reading to unset the readable status is done
with <a class="link" href="GCancellable.html#g-cancellable-reset" title="g_cancellable_reset ()"><code class="function">g_cancellable_reset()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pollfd</code></em> :</span></p></td>
<td> a pointer to a <a
href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GPollFD"
><span class="type">GPollFD</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE--CAPS"
><code class="literal">TRUE</code></a> if <em class="parameter"><code>pollfd</code></em> was successfully initialized, <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a> on
failure to prepare the cancellable.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2" title="g_cancellable_release_fd ()">
<a name="g-cancellable-release-fd"></a><h3>g_cancellable_release_fd ()</h3>
<pre class="programlisting">void g_cancellable_release_fd (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Releases a resources previously allocated by <a class="link" href="GCancellable.html#g-cancellable-get-fd" title="g_cancellable_get_fd ()"><code class="function">g_cancellable_get_fd()</code></a>
or <a class="link" href="GCancellable.html#g-cancellable-make-pollfd" title="g_cancellable_make_pollfd ()"><code class="function">g_cancellable_make_pollfd()</code></a>.
</p>
<p>
For compatibility reasons with older releases, calling this function
is not strictly required, the resources will be automatically freed
when the <em class="parameter"><code>cancellable</code></em> is finalized. However, the <em class="parameter"><code>cancellable</code></em> will
block scarce file descriptors until it is finalized if this function
is not called. This can cause the application to run out of file
descriptors when many <span class="type">GCancellables</span> are used at the same time.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2" title="g_cancellable_get_current ()">
<a name="g-cancellable-get-current"></a><h3>g_cancellable_get_current ()</h3>
<pre class="programlisting"><a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> * g_cancellable_get_current (void);</pre>
<p>
Gets the top cancellable from the stack.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> from the top of the stack, or <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>
if the stack is empty.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_pop_current ()">
<a name="g-cancellable-pop-current"></a><h3>g_cancellable_pop_current ()</h3>
<pre class="programlisting">void g_cancellable_pop_current (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Pops <em class="parameter"><code>cancellable</code></em> off the cancellable stack (verifying that <em class="parameter"><code>cancellable</code></em>
is on the top of the stack).</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_push_current ()">
<a name="g-cancellable-push-current"></a><h3>g_cancellable_push_current ()</h3>
<pre class="programlisting">void g_cancellable_push_current (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Pushes <em class="parameter"><code>cancellable</code></em> onto the cancellable stack. The current
cancllable can then be recieved using <a class="link" href="GCancellable.html#g-cancellable-get-current" title="g_cancellable_get_current ()"><code class="function">g_cancellable_get_current()</code></a>.
</p>
<p>
This is useful when implementing cancellable operations in
code that does not allow you to pass down the cancellable object.
</p>
<p>
This is typically called automatically by e.g. <a class="link" href="GFile.html" title="GFile"><span class="type">GFile</span></a> operations,
so you rarely have to call this yourself.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_reset ()">
<a name="g-cancellable-reset"></a><h3>g_cancellable_reset ()</h3>
<pre class="programlisting">void g_cancellable_reset (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Resets <em class="parameter"><code>cancellable</code></em> to its uncancelled state.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="g_cancellable_connect ()">
<a name="g-cancellable-connect"></a><h3>g_cancellable_connect ()</h3>
<pre class="programlisting"><a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"
>gulong</a> g_cancellable_connect (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"
>GCallback</a> callback,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> data_destroy_func);</pre>
<p>
Convenience function to connect to the <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a>
signal. Also handles the race condition that may happen
if the cancellable is cancelled right before connecting.
</p>
<p>
<em class="parameter"><code>callback</code></em> is called at most once, either directly at the
time of the connect if <em class="parameter"><code>cancellable</code></em> is already cancelled,
or when <em class="parameter"><code>cancellable</code></em> is cancelled in some thread.
</p>
<p>
<em class="parameter"><code>data_destroy_func</code></em> will be called when the handler is
disconnected, or immediately if the cancellable is already
cancelled.
</p>
<p>
See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for details on how to use this.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>callback</code></em> :</span></p></td>
<td> The <a
href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"
><span class="type">GCallback</span></a> to connect.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td> Data to pass to <em class="parameter"><code>callback</code></em>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data_destroy_func</code></em> :</span></p></td>
<td> Free function for <em class="parameter"><code>data</code></em> or <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The id of the signal handler or 0 if <em class="parameter"><code>cancellable</code></em> has already
been cancelled.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2" title="g_cancellable_disconnect ()">
<a name="g-cancellable-disconnect"></a><h3>g_cancellable_disconnect ()</h3>
<pre class="programlisting">void g_cancellable_disconnect (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gulong"
>gulong</a> handler_id);</pre>
<p>
Disconnects a handler from an cancellable instance similar to
<a
href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-disconnect"
><code class="function">g_signal_handler_disconnect()</code></a> but ensures that once this
function returns the handler will not run anymore in any thread.
</p>
<p>
This avoids a race condition where a thread cancels at the
same time as the cancellable operation is finished and the
signal handler is removed. See <a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> for
details on how to use this.
</p>
<p>
If <em class="parameter"><code>cancellable</code></em> is <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a> or <em class="parameter"><code>handler_id</code></em> is <code class="literal">0</code> this function does
nothing.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> A <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> or <a
href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>handler_id</code></em> :</span></p></td>
<td> Handler id of the handler to be disconnected, or <code class="literal">0</code>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.22</p>
</div>
<hr>
<div class="refsect2" title="g_cancellable_cancel ()">
<a name="g-cancellable-cancel"></a><h3>g_cancellable_cancel ()</h3>
<pre class="programlisting">void g_cancellable_cancel (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable);</pre>
<p>
Will set <em class="parameter"><code>cancellable</code></em> to cancelled, and will emit the
<a class="link" href="GCancellable.html#GCancellable-cancelled" title='The "cancelled" signal'><span class="type">"cancelled"</span></a> signal. (However, see the warning about
race conditions in the documentation for that signal if you are
planning to connect to it.)
</p>
<p>
This function is thread-safe. In other words, you can safely call
it from a thread other than the one running the operation that was
passed the <em class="parameter"><code>cancellable</code></em>.
</p>
<p>
The convention within gio is that cancelling an asynchronous
operation causes it to complete asynchronously. That is, if you
cancel the operation from the same thread in which it is running,
then the operation's <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> will not be invoked until
the application returns to the main loop.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> object.
</td>
</tr></tbody>
</table></div>
</div>
</div>
<div class="refsect1" title="Signal Details">
<a name="GCancellable.signal-details"></a><h2>Signal Details</h2>
<div class="refsect2" title='The "cancelled" signal'>
<a name="GCancellable-cancelled"></a><h3>The <code class="literal">"cancelled"</code> signal</h3>
<pre class="programlisting">void user_function (<a class="link" href="GCancellable.html" title="GCancellable">GCancellable</a> *cancellable,
<a
href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data) : Run Last</pre>
<p>
Emitted when the operation has been cancelled.
</p>
<p>
Can be used by implementations of cancellable operations. If the
operation is cancelled from another thread, the signal will be
emitted in the thread that cancelled the operation, not the
thread that is running the operation.
</p>
<p>
Note that disconnecting from this signal (or any signal) in a
multi-threaded program is prone to race conditions. For instance
it is possible that a signal handler may be invoked even
<span class="emphasis"><em>after</em></span> a call to
<a
href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-handler-disconnect"
><code class="function">g_signal_handler_disconnect()</code></a> for that handler has already
returned.
</p>
<p>
There is also a problem when cancellation happen
right before connecting to the signal. If this happens the
signal will unexpectedly not be emitted, and checking before
connecting to the signal leaves a race condition where this is
still happening.
</p>
<p>
In order to make it safe and easy to connect handlers there
are two helper functions: <a class="link" href="GCancellable.html#g-cancellable-connect" title="g_cancellable_connect ()"><code class="function">g_cancellable_connect()</code></a> and
<a class="link" href="GCancellable.html#g-cancellable-disconnect" title="g_cancellable_disconnect ()"><code class="function">g_cancellable_disconnect()</code></a> which protect against problems
like this.
</p>
<p>
An example of how to us this:
</p>
<div class="informalexample"><pre class="programlisting">
/* Make sure we don't do any unnecessary work if already cancelled */
if (g_cancellable_set_error_if_cancelled (cancellable))
return;
/* Set up all the data needed to be able to
* handle cancellation of the operation */
my_data = my_data_new (...);
id = 0;
if (cancellable)
id = g_cancellable_connect (cancellable,
G_CALLBACK (cancelled_handler)
data, NULL);
/* cancellable operation here... */
g_cancellable_disconnect (cancellable, id);
/* cancelled_handler is never called after this, it
* is now safe to free the data */
my_data_free (my_data);
</pre></div>
<p>
</p>
<p>
Note that the cancelled signal is emitted in the thread that
the user cancelled from, which may be the main thread. So, the
cancellable signal should not do something that can block.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
<td> a <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>user data set when the signal handler was connected.</td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.11</div>
</body>
</html>